@codesys/mcp-toolkit 1.5.8 → 2.0.0

package/watcher/mcp_sim.py

@@ -0,0 +1,246 @@
+# -*- coding: utf-8 -*-
+# CODESYS's own simulation: runs the active application inside CODESYS, with no
+# controller involved. Runs inside CODESYS (IronPython 2.7) and under CPython 3
+# with a fake scriptengine in tests. Keep this file ASCII-only.
+#
+# Every online call first checks that the device is in simulation mode, so these
+# operations can't reach a controller. While a simulation runs the project is
+# locked, so the simulation flag on the device is never saved into it.
+from __future__ import print_function
+
+import scriptengine as se
+
+import mcp_ops
+from mcp_compat import to_text
+from mcp_ops import Ctx, OpError, _safe
+
+SIM = {"online": None, "device": None, "project": None, "was_dirty": False, "forced": set(), "cycles": 0}
+
+# Operations that change the project, or could save the simulation flag into it.
+LOCKED = (
+    "project.open", "project.open_new", "project.create_empty", "project.save", "project.close",
+    "object.write", "object.create", "object.delete", "object.rename", "object.import_xml",
+    "libraries.add", "libraries.remove", "task.configure", "build",
+)
+
+# Between single cycles: the command returns before the cycle has run.
+CYCLE_PAUSE_MS = 100
+MAX_CYCLES = 1000
+# Long enough for CODESYS to refresh a value it monitors (see _read).
+READ_SETTLE_MS = 150
+
+
+def _require_simulation():
+    device = SIM["device"]
+    if device is None or not device.get_simulation_mode():
+        raise OpError("not_simulating", "The device is not in simulation mode, so the toolkit won't go online.")
+
+
+def _online():
+    if SIM["online"] is None:
+        raise OpError("not_running", "The CODESYS simulation isn't running. Call codesys_sim_start first.")
+    _require_simulation()
+    return SIM["online"]
+
+
+def _pause(ms):
+    if not hasattr(se, "FAKE"):
+        se.system.delay(ms)
+
+
+def _device_of(app):
+    """The outermost device above the application."""
+    found = None
+    obj = app
+    while obj is not None:
+        if _safe(lambda: obj.is_device, False):
+            found = obj
+        obj = _safe(lambda: obj.parent)
+    if found is None:
+        raise OpError("no_device", "No device found above the application.")
+    return found
+
+
+def _status():
+    online = SIM["online"]
+    if online is None:
+        return {"running": False}
+    return {
+        "running": True,
+        "state": to_text(online.application_state),
+        "operation": to_text(online.operation_state),
+        "forced": sorted(SIM["forced"]),
+        "cycles": SIM["cycles"],
+    }
+
+
+def _release():
+    """Take the device out of simulation mode and leave the project as it was."""
+    device, proj, was_dirty = SIM["device"], SIM["project"], SIM["was_dirty"]
+    SIM.update({"online": None, "device": None, "project": None, "was_dirty": False, "forced": set(), "cycles": 0})
+    if device is not None:
+        device.set_simulation_mode(False)
+    if proj is not None and not was_dirty:
+        proj.save()  # same content as before; leaves no unsaved change behind
+
+
+def _stop():
+    online = SIM["online"]
+    try:
+        _safe(lambda: online.unforce_all_values())
+        online.logout()
+    finally:
+        _release()
+
+
+def op_sim_start(args):
+    c = Ctx()
+    if c.app is None:
+        raise OpError("no_application", "The project has no active application to simulate.")
+    if SIM["online"] is not None:
+        _stop()
+    SIM["was_dirty"] = bool(_safe(lambda: c.proj.dirty, False))
+    SIM["project"] = c.proj
+    SIM["device"] = _device_of(c.app)
+    try:
+        SIM["device"].set_simulation_mode(True)
+        _require_simulation()
+        online = se.online.create_online_application(c.app)
+        online.login(se.OnlineChangeOption.Never, True)
+    except BaseException:
+        _release()
+        raise
+    SIM["online"] = online
+    if args.get("run"):
+        online.start()
+    return _status()
+
+
+def op_sim_stop(args):
+    if SIM["online"] is not None:
+        _stop()
+    return _status()
+
+
+def op_sim_status(args):
+    return _status()
+
+
+def op_sim_control(args):
+    online = _online()
+    action = args["action"]
+    if action == "run":
+        online.start()
+    elif action == "stop":
+        online.stop()
+    elif action in ("reset_warm", "reset_cold"):
+        online.reset(se.ResetOption.Warm if action == "reset_warm" else se.ResetOption.Cold, True)
+        SIM["forced"].clear()  # a reset releases forced values
+    else:
+        raise OpError("bad_request", "Unknown action: %s" % action)
+    return _status()
+
+
+def op_sim_cycle(args):
+    online = _online()
+    count = int(args.get("count") or 1)
+    if count < 1 or count > MAX_CYCLES:
+        raise OpError("bad_request", "count must be between 1 and %d." % MAX_CYCLES)
+    if to_text(online.application_state).lower() == "run":
+        online.stop()
+    command = se.system.commands["online", "singlecycleactiveapp"]
+    for _ in range(count):
+        command.execute()
+        SIM["cycles"] += 1
+        _pause(CYCLE_PAUSE_MS)
+    return _status()
+
+
+def _read(online, names):
+    """Current values and errors by name. CODESYS answers from its monitoring cache, so
+    the first read after a change can return the old value: read once, let it refresh, read again."""
+    _read_once(online, names)
+    _pause(READ_SETTLE_MS)
+    return _read_once(online, names)
+
+
+def _read_once(online, names):
+    """Values and errors by name. One bad name must not hide the good ones."""
+    try:
+        return dict(zip(names, [to_text(v) for v in online.read_values(names)])), {}
+    except Exception:
+        values, errors = {}, {}
+        for name in names:
+            try:
+                values[name] = to_text(online.read_value(name))
+            except Exception as e:
+                errors[name] = to_text(e)
+        return values, errors
+
+
+def op_sim_read(args):
+    values, errors = _read(_online(), args["names"])
+    return {"values": values, "errors": errors}
+
+
+def _prepare(online, values):
+    """Queue values, after checking every name, so a bad name leaves nothing queued."""
+    names = sorted(values)
+    errors = _read_once(online, names)[1]
+    if errors:
+        raise OpError("unknown_variable", "; ".join("%s: %s" % (n, errors[n]) for n in sorted(errors)))
+    for name in names:
+        online.set_prepared_value(name, to_text(values[name]))
+
+
+def op_sim_write(args):
+    online = _online()
+    _prepare(online, args["values"])
+    online.write_prepared_values()
+    return _status()
+
+
+def op_sim_force(args):
+    online = _online()
+    _prepare(online, args["values"])
+    online.force_prepared_values()
+    SIM["forced"].update(args["values"].keys())
+    return _status()
+
+
+def op_sim_unforce(args):
+    online = _online()
+    names = args.get("names")
+    if names:
+        for name in names:
+            online.set_prepared_value(name, se.online.UNFORCE)
+        online.force_prepared_values()
+        SIM["forced"].difference_update(names)
+    else:
+        online.unforce_all_values()
+        SIM["forced"].clear()
+    return _status()
+
+
+def _locked(fn):
+    def run(args):
+        if SIM["online"] is not None:
+            raise OpError("simulation_running", "The CODESYS simulation is running, so the project is locked. Call codesys_sim_stop first.")
+        return fn(args)
+    return run
+
+
+for _name in LOCKED:
+    mcp_ops.OPS[_name] = _locked(mcp_ops.OPS[_name])
+
+mcp_ops.OPS.update({
+    "sim.start": op_sim_start,
+    "sim.stop": op_sim_stop,
+    "sim.status": op_sim_status,
+    "sim.control": op_sim_control,
+    "sim.cycle": op_sim_cycle,
+    "sim.read": op_sim_read,
+    "sim.write": op_sim_write,
+    "sim.force": op_sim_force,
+    "sim.unforce": op_sim_unforce,
+})

package/watcher/watcher.py

@@ -0,0 +1,255 @@
+# -*- coding: utf-8 -*-
+# codesys-mcp-toolkit v2 watcher.
+#
+# Started by the MCP server as:  CODESYS.exe --profile="..." --noUI --runscript="<dir>/watcher.py"
+# Environment (inherited from the server):
+#   CODESYS_MCP_DIR         session folder (requests/, results/, heartbeat.json, ready.json, watcher.log)
+#   CODESYS_MCP_SCRIPTS     folder holding this file and its modules
+#   CODESYS_MCP_PARENT_PID  server PID; the watcher exits when it is gone
+#
+# Protocol: the server writes requests/<id>.json ({"id","op","args","deadline_ms"}) via tmp+rename.
+# The watcher handles one request at a time and writes results/<id>.json
+# ({"id","ok","result"} or {"id","ok":false,"error":{"code","message","detail"}}).
+# Requests are JSON op names + arguments; no code is ever generated or exec'd.
+#
+# Keep this file ASCII-only (IronPython 2.7 inside CODESYS).
+from __future__ import print_function
+
+import os
+import re
+import sys
+import time
+import traceback
+
+SCRIPTS = os.environ.get("CODESYS_MCP_SCRIPTS")
+if SCRIPTS and SCRIPTS not in sys.path:
+    sys.path.insert(0, SCRIPTS)
+
+from mcp_compat import current_pid, now, pid_alive, read_json, remove_file, retry_fs, to_text, write_json_atomic  # noqa: E402
+
+SESSION = os.environ["CODESYS_MCP_DIR"]
+PARENT_PID = int(os.environ.get("CODESYS_MCP_PARENT_PID") or "0")
+REQ_DIR = os.path.join(SESSION, "requests")
+RES_DIR = os.path.join(SESSION, "results")
+HEARTBEAT = os.path.join(SESSION, "heartbeat.json")
+READY = os.path.join(SESSION, "ready.json")
+LOG = os.path.join(SESSION, "watcher.log")
+
+DIALOG = os.path.join(SESSION, "dialog.json")
+
+PID = current_pid()
+STATE = {"count": 0, "last_beat": 0.0, "busy_since": None, "op": None}
+
+# A dialog must stay up this long before the server is told, so brief windows don't count.
+DIALOG_GRACE_S = 10.0
+
+
+def log(msg):
+    try:
+        f = open(LOG, "a")
+        try:
+            f.write("%s %s\n" % (time.strftime("%H:%M:%S"), to_text(msg).encode("ascii", "replace").decode("ascii")))
+        finally:
+            f.close()
+    except Exception:
+        pass
+
+
+def beat(state, op=None, rid=None, deadline_ms=None):
+    # A heartbeat that cannot be written (file held open past the retries) must not
+    # kill the watcher: log it and go on. If it keeps failing, the server sees a
+    # stale heartbeat and reports the watcher as hung, which is the right signal.
+    t = now()
+    try:
+        write_json_atomic(HEARTBEAT, {
+            "pid": PID, "ts": t, "state": state, "op": op, "id": rid,
+            "deadline": (t + deadline_ms / 1000.0) if deadline_ms else None,
+            "count": STATE["count"],
+        })
+    except Exception as e:
+        log("heartbeat write failed (%s): %s" % (state, to_text(e)))
+    STATE["last_beat"] = t
+
+
+def setup_prompts(se):
+    # Never block on a modal dialog: suppress with defaults and log them.
+    # SP21 only has the old prompt_handling; newer versions have script_prompt_handling.
+    try:
+        se.system.script_prompt_handling = se.ScriptPromptHandling.LogPrompts
+        return "script_prompt_handling=LogPrompts"
+    except Exception:
+        pass
+    try:
+        se.system.prompt_handling = se.PromptHandling.LogSimplePrompts
+        return "prompt_handling=LogSimplePrompts"
+    except Exception as e:
+        return "prompt handling not set: %s" % e
+
+
+def scripting_version():
+    # In CODESYS, sys.version ends in "ScriptEngine.plugin 4.2.0.0".
+    m = re.search(r"ScriptEngine\.plugin\s+([0-9.]+)", sys.version)
+    return m.group(1) if m else None
+
+
+def find_dialog():
+    # A session without a UI has no open forms and no main window (checked on SP21 and
+    # SP22), so a modal form or a main window means CODESYS is waiting for an answer.
+    from System.Windows.Forms import Application
+    from System.Diagnostics import Process
+    for f in Application.OpenForms:
+        if f.Modal:
+            return to_text(f.Text) or "(untitled)"
+    return to_text(Process.GetCurrentProcess().MainWindowTitle) or None
+
+
+def watch_dialogs():
+    # Runs beside the request loop. A dialog blocks that loop for good and nobody can
+    # answer it in a session without a window, so tell the server (dialog.json).
+    import clr
+    clr.AddReference("System.Windows.Forms")
+    title, since, reported, failed = None, 0.0, False, False
+    while True:
+        time.sleep(1.0)
+        busy = STATE["busy_since"]
+        current = None
+        if busy is not None and now() - busy > 2.0:
+            try:
+                current = find_dialog()
+            except Exception as e:  # e.g. the form list changed while it was read
+                if not failed:
+                    log("dialog check failed: %s" % to_text(e))
+                failed = True
+        if current != title:
+            title, since = current, now()
+            if current:
+                log("dialog up during %s: %s" % (STATE["op"], current))
+            elif reported:
+                remove_file(DIALOG)
+                reported = False
+        elif current and not reported and now() - since >= DIALOG_GRACE_S:
+            write_json_atomic(DIALOG, {"title": current, "op": STATE["op"]})
+            reported = True
+
+
+def start_dialog_watch():
+    import threading
+
+    def run():
+        try:
+            watch_dialogs()
+        except BaseException as e:
+            log("dialog watch stopped: %s" % to_text(e))
+    t = threading.Thread(target=run)
+    t.daemon = True
+    t.start()
+
+
+def sleep_ms(se, ms):
+    delay = getattr(getattr(se, "system", None), "delay", None)
+    if delay is not None and not hasattr(se, "FAKE"):
+        try:
+            delay(ms)
+            return
+        except Exception:
+            pass
+    time.sleep(ms / 1000.0)
+
+
+def next_request():
+    try:
+        names = sorted(n for n in os.listdir(REQ_DIR) if n.endswith(".json"))
+    except OSError:
+        return None
+    return names[0] if names else None
+
+
+def handle(ops_mod, fname):
+    path = os.path.join(REQ_DIR, fname)
+    rid = fname[:-5]
+    try:
+        # Another process (an antivirus scan, the indexer) can hold a new file for a moment.
+        req = retry_fs(read_json, path)
+    except Exception as e:
+        remove_file(path)
+        write_json_atomic(os.path.join(RES_DIR, rid + ".json"), {
+            "id": rid, "ok": False, "error": {"code": "bad_request", "message": "Unreadable request: %s" % e}})
+        return True
+    remove_file(path)
+    rid = req.get("id") or rid
+    op = req.get("op")
+    args = req.get("args") or {}
+    STATE["count"] += 1
+    beat("busy", op, rid, req.get("deadline_ms"))
+    started = now()
+    STATE["op"] = op
+    STATE["busy_since"] = started
+    stop = False
+    if op == "shutdown":
+        res = {"id": rid, "ok": True, "result": {"bye": True}}
+        stop = True
+    else:
+        fn = ops_mod.OPS.get(op)
+        if fn is None:
+            res = {"id": rid, "ok": False, "error": {"code": "unknown_op", "message": "Unknown op: %s" % op}}
+        else:
+            try:
+                res = {"id": rid, "ok": True, "result": fn(args)}
+            except ops_mod.OpError as e:
+                res = {"id": rid, "ok": False, "error": {"code": e.code, "message": to_text(e.message)}}
+            except BaseException as e:  # IronPython: KeyboardInterrupt is not an Exception
+                res = {"id": rid, "ok": False, "error": {
+                    "code": "codesys_error", "message": to_text(e) or e.__class__.__name__,
+                    "detail": to_text(traceback.format_exc())}}
+    STATE["busy_since"] = None
+    res["ms"] = int((now() - started) * 1000)
+    # Go idle before publishing the result: once the server sees the result it may
+    # read the heartbeat right away, and it must not find this op still "busy".
+    beat("idle")
+    write_json_atomic(os.path.join(RES_DIR, rid + ".json"), res)
+    log("%s %s %s %dms" % (rid, op, "ok" if res.get("ok") else res["error"]["code"], res["ms"]))
+    return not stop
+
+
+def main():
+    for d in (REQ_DIR, RES_DIR):
+        if not os.path.isdir(d):
+            os.makedirs(d)
+    log("watcher starting pid=%s parent=%s python=%s" % (PID, PARENT_PID, sys.version.split()[0]))
+    import scriptengine as se
+    import mcp_ops
+    import mcp_sim  # noqa: F401 (adds its operations to mcp_ops.OPS)
+    prompts = setup_prompts(se)
+    log(prompts)
+    if not hasattr(se, "FAKE"):
+        start_dialog_watch()
+    beat("idle")
+    write_json_atomic(READY, {"pid": PID, "ts": now(), "python": sys.version.split()[0], "prompts": prompts, "scripting": scripting_version()})
+    last_parent_check = 0.0
+    while True:
+        t = now()
+        if PARENT_PID and t - last_parent_check > 2.0:
+            last_parent_check = t
+            if not pid_alive(PARENT_PID):
+                log("parent %s gone; exiting" % PARENT_PID)
+                break
+        fname = next_request()
+        if fname:
+            if not handle(mcp_ops, fname):
+                log("shutdown requested")
+                break
+            continue
+        if t - STATE["last_beat"] > 1.0:
+            beat("idle")
+        sleep_ms(se, 40)
+    beat("stopped")
+
+
+try:
+    main()
+except BaseException:
+    log("watcher crashed: " + traceback.format_exc())
+    try:
+        beat("crashed")
+    except Exception:
+        pass

package/.claude/settings.local.json

@@ -1,29 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(grep:*)",
-      "Bash(grep:*)",
-      "Bash(npm version:*)",
-      "Bash(npm version:*)",
-      "Bash(cat:*)",
-      "Bash(cat:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm install:*)",
-      "Bash(npm install:*)",
-      "Bash(npx tsc:*)",
-      "Bash(npx tsc:*)",
-      "Bash(npm pack:*)",
-      "Bash(npm pack:*)",
-      "Bash(npm publish:*)",
-      "Bash(npm publish:*)",
-      "Bash(ls:*)",
-      "Bash(ls:*)",
-      "Bash(mkdir:*)",
-      "Bash(mkdir:*)",
-      "Bash(node:*)",
-      "Bash(node:*)"
-    ],
-    "deny": []
-  }
-}

package/CLAUDE.md

@@ -1,26 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Build Commands
-- `npm run build` - Compile TypeScript to JavaScript
-- `npm start` - Start the MCP server
-- `tsc` - Run TypeScript compiler manually
-
-## Coding Style Guidelines
-- **Imports**: Import 'os' first if needed, then group related imports
-- **Naming**: Use camelCase for variables/functions, PascalCase for classes/interfaces
-- **Types**: TypeScript with interfaces for structured data, avoid implicit 'any'
-- **Error Handling**: Check conditions early, throw meaningful errors with context
-- **Comments**: Add JSDoc comments for functions, especially exported ones
-- **Formatting**: Follow existing indentation (2 spaces) and code patterns
-- **Path Handling**: Use path.join() for cross-platform compatibility
-- **Promises**: Prefer async/await over raw promises when possible
-- **Logging**: Use console.error for diagnostic/debug messages
-
-## Project Structure
-- `/src` - TypeScript source files
-- `/scripts` - Python scripts for CODESYS integration
-- `/dist` - Compiled JavaScript (generated)
-- `/docs` - Documentation files
-- `/examples` - Example configurations and usage

package/CONTRIBUTING.md

@@ -1,72 +0,0 @@
-# Contributing to @codesys/mcp-toolkit
-
-Thank you for considering contributing to the CODESYS MCP Toolkit! This document provides guidelines and steps for contributing.
-
-## Code of Conduct
-
-Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.
-
-## How Can I Contribute?
-
-### Reporting Bugs
-
-Bug reports help improve the project! When reporting bugs:
-
-1. Check if the bug has already been reported
-2. Use the bug report template
-3. Include detailed steps to reproduce the issue
-4. Describe the expected vs. actual behavior
-5. Include screenshots if applicable
-6. Provide environment details (OS, Node.js version, etc.)
-
-### Suggesting Features
-
-We welcome feature suggestions! When suggesting features:
-
-1. Describe the problem your feature would solve
-2. Explain how your feature would work
-3. Consider potential alternatives
-4. Provide examples of similar features in other projects (if applicable)
-
-### Pull Requests
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Run tests and ensure they pass
-5. Commit your changes (`git commit -m 'Add amazing feature'`)
-6. Push to your branch (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
-
-## Development Setup
-
-1. Clone the repository
-   ```bash
-   git clone https://github.com/yourusername/codesys-mcp-toolkit.git
-   cd codesys-mcp-toolkit
-   ```
-
-2. Install dependencies
-   ```bash
-   npm install
-   ```
-
-3. Build the project
-   ```bash
-   npm run build
-   ```
-
-## Style Guidelines
-
-- Follow existing code formatting patterns
-- Use meaningful variable and function names
-- Add comments where necessary to explain complex logic
-- Update documentation when changing functionality
-
-## Testing
-
-- Add tests for new features
-- Ensure all tests pass before submitting a PR
-- Consider edge cases in your tests
-
-Thank you for contributing!