te1000-mcp

A Model Context Protocol server for Beckhoff TwinCAT 3 engineering automation — drive the TE1000 / XAE Automation Interface from an AI agent or any MCP client.

te1000-mcp exposes the TwinCAT XAE engineering surface — the System Manager tree, PLC project authoring, IO/EtherCAT configuration, variable linking, builds, and runtime deployment — as a compact set of MCP tools. It talks to a running XAE Shell through the TE1000 Automation Interface (COM/DTE), so an agent can configure and build a TwinCAT project the same way an engineer would in the GUI.

A Node MCP front (index.js) owns the MCP protocol, tool schemas, and confirmation guards; the COM/DTE work runs in a persistent native C#/.NET daemon (Te1000Daemon.exe) that the front talks to over a Windows named pipe. The daemon is the sole backend. See How it works.

Contents

• Highlights

• How it works

• Requirements

• Install

• Build the daemon

• Configure your MCP client

• Environment variables

• Quickstart

• Tool reference

• Safety & guards

• Reliability: dialog watchdog & PLC session control

• Troubleshooting

• Examples

• Documentation

• Contributing

• License

Related MCP server: TwinCAT Validator MCP Server

Highlights

• 25 noun-grouped tools covering the automatable TE1000 surface — tree, IO/EtherCAT, linking, PLC project & POU authoring, libraries, tasks, mapping, routes, fieldbuses, TcCOM, C++, measurement/scope, licensing, and variants.

• Batch-first — every multi-item operation has a *_batch form that runs N operations in one DTE attach and returns a compact continue-on-error roll-up, instead of paying a process spawn + attach per call.

• Native EtherCAT builder — tc_ethercat creates fully-populated EtherCAT boxes (correct identity, SyncManagers, FMMUs, PDOs) for any device class by the GUI's own "Add Box" route, driven from the device's ESI.

• Surgical PLC code edits — plc_pou reads, greps, and patches declaration/implementation text in place and returns only the changed region, keeping agent context small.

• Safe by default — destructive and runtime-affecting actions are confirmation-gated; the safety project is never written to, by policy.

• Resilient to GUI modals — a dialog watchdog detects and (optionally) auto-dismisses modal dialogs that would otherwise hang a synchronous COM call forever.

• Persistent native daemon — a long-lived C#/.NET daemon holds the COM session and caches the project tree and POU source text, so warm plc_pou search runs roughly 500× faster than the old per-call spawn model.

How it works

  MCP client (agent)
        │  stdio (JSON-RPC, MCP)
        ▼
  index.js ───────────────► Te1000Daemon.exe ──COM/DTE──► XAE Shell (TE1000)
   (Node 20)  named pipe     (persistent, x64,            running TwinCAT project
   daemonClient.js           net472, STA COM session)
   toolSchemas.js

Two cooperating processes:

• Node MCP front (index.js) — speaks MCP/JSON-RPC over stdio, validates input with zod, single-sources every tool's input schema from toolSchemas.js, enforces the confirmation-token guards, and maps each tool action onto a fine-grained bridge action name. It routes those actions to the daemon over a named pipe (daemonClient.js).

• Native daemon (daemon/Te1000Daemon.exe) — a persistent net472/x64 process that acquires the DTE + ITcSysManager once and keeps them, runs the dialog watchdog on an internal thread, caches the System Manager tree and POU source text, and serves the front over the pipe. It implements the same 164 bridge actions and returns the same JSON, so the tool surface is unchanged.

Pipe protocol

The front and daemon exchange newline-delimited JSON over \\.\pipe\te1000-mcp (name overridable via TE1000_DAEMON_PIPE):

  request:   {"id": "<n>", "action": "<bridge_action>", "payload": { … }}
  response:  {"id": "<n>", "ok": true,  "result": { … }}
           | {"id": "<n>", "ok": false, "error": "…", "errorKind": "com_error|dialog_blocked|timeout", "dialog": { … }}

Responses are correlated by id. The daemon serializes every COM call through a single STA worker thread, so concurrent pipe clients are safe (XAE serializes anyway). The daemon also answers two COM-free meta actions used for health checks: ping and list_actions.

Why a daemon — the performance win

An earlier model spawned a fresh 32-bit powershell.exe bridge (plus a second watcher process) on every call. Each spawn re-acquired the DTE/ITcSysManager COM handles (a Running-Object-Table walk + Marshal.GetActiveObject), JIT-compiled the inline Add-Type Win32 helpers, and — for plc_pou.find/search — re-walked the entire project tree from the root (O(tree-size), ~2,900 COM round-trips on a full project), so latency grew with project size.

The persistent daemon removes all of that from the hot path:

• Persistent COM session (ComSession.cs) — the DTE + sysmanager are acquired once, health-checked with a cheap property read, and transparently reconnected if stale.

• Two-layer tree cache (TreeCache.cs) — per-object decl/impl source text and a flat enumeration of the project's code objects are memoized, so a warm full-project search does zero COM tree-walk. This is the ~500× warm-search speed-up.

• Edit watcher (EditWatcher.cs) — an on-demand DTE.Documents/.Saved dirty check plus a FileSystemWatcher over the project directory invalidate the cache so it never serves stale source for an object you are editing in the IDE (or that changed on disk).

• Internal dialog watcher (DialogWatcher.cs) — runs on its own thread, so there is no per-call watcher process. See Reliability.

Build the daemon with daemon/build.ps1 (in-box .NET Framework MSBuild — no SDK/NuGet). The daemon requires the 64-bit TcXaeShell (DTE.17.0). See docs/architecture.md for the end-to-end design and docs/csharp-daemon-validation.md for the build/cut-over/validation guide.

Requirements

The XAE ProgID defaults to TcXaeShell.DTE.17.0. Override it with the TE1000_PROGID environment variable if your installation differs.

The daemon is not auto-built — build it once with daemon/build.ps1 (see Build the daemon); thereafter the MCP front auto-spawns the prebuilt Te1000Daemon.exe on first use. If the exe is absent, build it before the front can serve calls.

Install

git clone https://github.com/Edge-JB/TwinCAT-XAE-MCP.git
cd TwinCAT-XAE-MCP
npm install

Verify the server starts:

node index.js
# -> te1000-mcp server running on stdio   (Ctrl-C to exit)

The server communicates over stdio and is normally launched by an MCP client, not by hand. Running it directly just waits for a client on stdin.

Build the daemon

The native daemon is the backend, which you build once:

powershell -ExecutionPolicy Bypass -File daemon\build.ps1
# -> daemon\bin\Release\Te1000Daemon.exe   (Release, x64, net472)

• Uses the in-box .NET Framework MSBuild (C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe) — no .NET SDK, no NuGet, no internet. The csproj is old-style (non-SDK) and targets net472; the produced x64 exe also runs on the net48 runtime.

• References TCatSysManagerLib.dll (embedded interop) for the handful of vtable-only IUnknown interfaces that late-bound dynamic can't reach (ITcPlcProject, etc.). build.ps1 probes the known TwinCAT install paths; if yours differs, edit the <HintPath> in daemon/Te1000Daemon.csproj and rebuild. Pass -Debug for a Debug build.

• After building, the MCP front auto-spawns the exe (detached, windowsHide) on the first call and connects to its pipe. The daemon is single-instance per pipe name (named mutex), so duplicate spawns are harmless, and it is detached so it survives an MCP-front restart. Verify it independently with no XAE attached:

  node daemon\test-ping.js     # spawns the daemon on a test pipe, round-trips ping

Configure your MCP client

Point your client at the absolute path of index.js in your clone. Example (Claude Desktop / Claude Code / any MCP client that reads this shape):

{
  "mcpServers": {
    "te1000": {
      "command": "node",
      "args": ["C:\\path\\to\\TwinCAT-XAE-MCP\\index.js"]
    }
  }
}

A ready-to-edit copy lives at examples/mcp-config.json.

Environment variables

All optional. The first group is read by the Node front (index.js / daemonClient.js); the second by the native daemon process. Defaults are from the source.

Read by the Node front:

Read by the daemon:

The daemon also accepts CLI flags (--pipe, --no-watch, --no-autodismiss, --grace-ms, --allowlist). The front sets these from the dialog-watch env vars above when it spawns the daemon — you normally don't pass them by hand.

Caveat — spawn-time only. TE1000_DIALOG_WATCH, TE1000_DIALOG_AUTODISMISS, and TE1000_DIALOG_GRACE_MS are read by the Node front only when it spawns the daemon, and are translated into the daemon's --no-watch / --no-autodismiss / --grace-ms flags. The daemon is single-instance per pipe, so changing one of these has no effect on an already-running daemon — kill that daemon process and let the front re-spawn it before the new value takes effect.

Quickstart

With XAE Shell open on your solution, an agent can drive a full configure → build loop. A typical session (tool name + arguments shown):

# 1. Confirm the server is attached and a solution is open
xae            action: "status"

# 2. Inspect the IO tree
tc_tree        action: "children"  path: "TIID^Device 2 (EtherCAT)"

# 3. Add a populated EtherCAT rack from its ESI (digital in/out + analog)
tc_ethercat    racks: [{
                 parent: "TIID^Device 2 (EtherCAT)^R01.Main.N01 (EK1200)",
                 modules: [{ type: "EL1008" }, { type: "EL2008" }, { type: "EL3064" }]
               }]
               save: true

# 4. Link a PLC input to a terminal channel
tc_link        action: "link"
               a: "TIPC^MyPlc^MyPlc Instance^PlcTask Inputs^MAIN.bStart"
               b: "TIID^Device 2 (EtherCAT)^Term 1^Channel 1^Input"

# 5. Build the solution
xae_build      action: "build"

# 6. (Optional, guarded) download to the target runtime
plc_download   confirm: "ALLOW_PLC_DOWNLOAD"

More end-to-end recipes — bulk linking, parameter edits via set_xml, POU authoring — are in examples/.

Tool reference

Paths into the System Manager tree use ^ separators, e.g. TIID^Device 2 (EtherCAT)^Box 1^Term 5^Channel 1. The leading token is the tree root (TIPC = PLC, TIID = IO, TINC = NC, TIRC = realtime/license, …).

Engineering & build

System Manager tree, IO & linking

PLC project & code

Realtime, fieldbus & platform

Runtime (guarded)

🔒 = confirmation-gated. See Safety & guards. Full action signatures, batch semantics, and return shapes are documented in docs/tools.md.

Safety & guards

The server never auto-activates, auto-restarts, or auto-deploys. Any action that changes the target runtime, deletes a node, or alters licensing is blocked unless you pass the matching confirm token:

Safety project policy. Nothing in this toolchain writes toward the TwinSAFE safety project. Every authoring tool refuses safety-rooted (TISC) paths via an internal guard. Safety remains read-only/diagnostic.

Reliability: dialog watchdog & PLC session control

A synchronous DTE/COM call blocks inside XAE's modal message loop if XAE raises a modal dialog (save-changes, "file changed externally", activate confirm, license prompt) — which would hang the MCP call and the calling agent indefinitely.

• Dialog watchdog. This runs as an internal thread of the daemon (DialogWatcher.cs) that polls (~750 ms) for an application-modal dialog owned by the XAE process. It detects application-modal dialogs owned by XAE and either auto-dismisses them (if they match a rule in dialog-allowlist.json) or reports the dialog's title, body, and buttons back to the agent and abandons the call. If a non-allowlisted modal persists past TE1000_DIALOG_GRACE_MS, the daemon recycles its COM worker thread (re-acquiring the session on a fresh STA thread) without killing the daemon, so subsequent calls recover once the dialog is cleared. Detection is dialog-driven, not a wall-clock timeout, so long legitimate builds are never killed. The allowlist ships empty (report-only by default) and must never auto-answer Activate / Run-mode / restart / download / safety prompts.

• Interactive resolution. When a dialog is not in the allowlist, the reported error tells the agent to ask the user which button to press (and whether to remember it), then call xae dialog_resolve {button, remember?}. That action clicks the chosen button on the live dialog; with remember:true it appends an auto-dismiss rule to dialog-allowlist.json and hot-applies it to the running watcher (no restart). Destructive prompts (activate / run-mode / restart / download / boot project / TwinSAFE / safety) are refused for auto-remember — the one-time chosen click still happens, but no rule is persisted (rememberRefused is reported). Use xae dialog_probe (read-only) to inspect the current dialog first.

• PLC session control (powershell/plc-session.ps1) uses UI Automation to read and toggle the Login/Logout state (the DTE Login/Logout commands are unreachable on the 64-bit shell). plc_download auto-logs-out first (by default) so deferred source edits compile before the boot project is generated. It never logs back in.

Full details: docs/operations.md.

Troubleshooting

• Te1000Daemon.exe not found — build it: daemon\build.ps1. The front cannot serve calls until the daemon is built.

• Build fails on TCatSysManagerLib — the DLL wasn't found at the probed TwinCAT paths. Edit the <HintPath> in daemon/Te1000Daemon.csproj to your install and rebuild.

• Rebuild fails with the exe locked — a daemon is still running. Stop it first: Get-Process Te1000Daemon | Stop-Process, then rebuild.

• Daemon won't start / stale behavior — kill it (above) and let the front re-spawn a fresh one on the next call. Enable TE1000_DAEMON_DEBUG=1 to capture %TEMP%\te1000-daemon-<pipe>.log.

• Wrong XAE instance picked (several open) — set TE1000_MCP_SOLUTION_PATH to the solution's full path to pin the daemon to that instance.

• A modal dialog is blocking calls — clear it on the machine, or add a rule to dialog-allowlist.json (never for Activate / restart / download / safety prompts). The daemon picks up the allowlist on start.

Examples

The examples/ directory contains:

• mcp-config.json — a drop-in client configuration.

• README.md — copy-pasteable recipes: building an EtherCAT rack, bulk-linking IO, editing terminal parameters via set_xml, authoring a POU, and a safe build → activate → download flow.

Documentation

Contributing

Contributions are welcome — see CONTRIBUTING.md for the architecture, the daemon build/dev loop, the action-handler contract, and the safety rules every change must respect. In short:

npm run check                                          # node --check index.js — syntax-validate the front
node daemon\test-ping.js                               # daemon process + pipe + JSON round-trip (no XAE)
powershell -ExecutionPolicy Bypass -File daemon\build.ps1   # rebuild the daemon after a C# change

License

MIT © Edge Automation.

Legal & trademarks

This is an independent, third-party project. It is not affiliated with, endorsed by, sponsored by, or supported by Beckhoff Automation GmbH & Co. KG.

All product names, logos, and brands are the property of their respective owners:

• Beckhoff®, TwinCAT®, TE1000, and XAE Shell are trademarks or registered trademarks of Beckhoff Automation GmbH & Co. KG.

• EtherCAT® is a registered trademark and patented technology, licensed by Beckhoff Automation GmbH, Germany.

These names are used for identification and descriptive purposes only; their use does not imply any affiliation with or endorsement by the trademark holders.

This project does not include, bundle, or redistribute any Beckhoff software. It automates a separately installed and licensed TwinCAT 3 / TE1000 environment that you must obtain from Beckhoff yourself. You are responsible for complying with all applicable Beckhoff license terms and for any action this tool performs against your engineering or runtime systems.

The software is provided "AS IS", without warranty of any kind, under the MIT License. See NOTICE for the full attributions.