The DSH TIA Portal plugin: wire an MCP gateway by talking, then verify with three prompts

2026-11-17来源 dev.toEnglish

There is exactly one thing you must not skip when you hand an AI agent the keys to a PLC project: make it prove it touched a tool.

The failure mode is quiet. The model writes a confident, well-formatted, entirely fabricated step list — it never called anything. The cheap test is one line: can it tell you the project name and the device model that are on your screen right now? If it cannot, nothing after that point is real.

Everything below ran against a real TIA Portal V19 project (empty project, CPU 1516-3 PN/DP) on a Windows machine. The numbers are wall-clock measurements, not estimates.

0. What has to be in place first

  • Windows with TIA Portal V19 or V20, and the current user in the Siemens TIA Openness local group.
  • A local MCP gateway running on the same machine as TIA Portal (the client can live elsewhere; the gateway cannot).
  • A desktop AI client that supports MCP plugins — here, DeepSeek Harness (DSH), desktop app or its web UI.

Why the gateway must sit next to TIA Portal: Openness is a local COM API. Anything that edits a project has to be in the same Windows session as the engineering environment. A remote HTTP bridge works for the client, never for the gateway.

1. Install: three clicks

  1. Open DSH, click Plugins (top left).
  2. Type the plugin name.
  3. Click install.

That registers five services: one local gateway plus four cloud ones (documentation retrieval, cloud simulation, a JSON ladder-document service, and ladder rendering). The four cloud services each need their own API key — an unconfigured service simply does not appear in the tool list, and the only trace is a 401 in the background log.

If you prefer the CLI: dsh plugin --profile desktop add <plugin> (use the CLI that ships with the desktop build).

Key trap: logging into the console does not display the key. You have to click "rotate key", at which point the new key is shown once and the old one dies immediately. Copy it, paste it into the matching TIA_*_KEY environment variable (or just tell the agent to write it into the config), then restart the client — the MCP connection is established at startup, so a restart is mandatory.

If a cloud service is missing from the tool list, go back to this step. 401 is almost never a network problem.

2. Prompt one: hand it the gateway

"The gateway is at http://192.168.1.110:8080/mcp. Configure it, connect to the project I have open, and tell me which project it is and how many devices there are."

It does three things: writes the address into its config, asks you to restart once, then connects on its own and reports back.

Check exactly three values:

It says Should be If it does not match
Connected to TIA Portal connected the gateway is not attached to a running Portal instance
Project name identical to the one open on your screen wrong project
Device count identical to the device tree the gateway is attached to another instance

Once that prompt passes, the chain is live. Underneath, exactly one value changed — the gateway address. You did not have to hand-edit it, but knowing its name matters: "what gateway address are you using right now?" is the question that resolves most later confusion.

If it returns 401, the gateway has token validation enabled: copy the token from the gateway console, paste it into the chat, let it rewrite the config, restart. Pasting a token into a chat log is a real trade-off — rotate it afterwards, which invalidates the old one immediately, then paste the new one once.

3. Prompts two to four: verify before you work

Tool inventory

"Which capabilities can you call right now? List them and count them."

Expect a specific number (34 in our build). If the count is off, or it says it cannot find any service, stop here.

Is it looking at your project

Ask for the device list and the block list, read-only. Compare against your screen. A model that never called a tool can guess plausible device names; it cannot guess your device count and your block names at the same time.

Did it actually read, or is it recalling

Ask a documentation question whose answer is version-specific, e.g. the parameter differences of TON between LAD and FBD. A correct answer that arrives together with a doc-search tool call is evidence. A correct answer with no tool call is luck.

All three passing is the gate. Below that line, an agent is autocomplete with extra steps.

4. Real work: three prompts and their timings

Prompt What it does Measured
"Show project state, then list devices, blocks and tag tables. Read-only — change nothing." state → devices → blocks < 1 s per step
"Add a device PLC_1, order number 6ES7 516-3AN00-0AB0 / V1.1, PLC type" resolve order number → create CPU 34.1 s
"Import this SCL as an FB into PLC_1, then compile only that block" import → compile → export back import 11.8 s (FB) / 0.6 s (OB, DB), compile 1.4 s, export 0.1 s

After the third prompt, the deliverable is not the model's summary. It is 0 errors / 0 warnings in the compile output plus the exported block file. That export is your evidence and your rollback point.

The timings also tell you when "slow" is normal: adding a CPU takes tens of seconds, importing SCL takes ten-plus. A sudden 10× slowdown is usually TIA Portal itself being busy, not the agent.

5. When it gets stuck: ask for the raw message

Models love to compress an error into "compilation failed, possibly a configuration issue", which is unactionable. Ask instead:

"Paste the tool's raw output. Do not summarize, do not rewrite."

What it says Actual cause What to reply
"everything returns 401" token missing, mistyped, or rotated without updating paste the new token, rewrite config, restart
"the tool list has no doc-search / simulation / rendering" that service's key is missing or the client was not restarted configure the key, restart
"cannot connect / connection refused" gateway not running, or address points at localhost from the wrong machine run it on the engineering PC, use that machine's IP
"call timed out" too many actions in one prompt one action per prompt; add the CPU first, import later
Inputs or outputs are used that do not exist in the configured hardware addresses point at rack I/O that is not configured (bare CPU + %Q0.0 always trips this) switch to %M and recompile — configuration mismatch, not a logic bug
VAR area is not allowed for blocks of type OB static variables inside an OB create a global single-instance DB, call it from OB1
invalid value for "VERSION" VERSION written into an instance DB FBs/OBs may carry a version, instance DBs may not
Block 'Main' is inconsistent (not compiled) previous compile failed, block is in an inconsistent state compile the block or the whole PLC first, then export

The bottom four are not environment problems — they are SCL rules inside TIA Portal that the model does not know by default. The tool reports them verbatim; the agent has to be willing to read that message and try again. That habit beats any prompt template.

6. Three safety habits

  1. Run the whole flow on a scratch project first. Empty project or a copy. Every acceptance criterion should be reproducible before you touch production.
  2. One block per prompt. "Change this FB and compile it" is verifiable. "Refactor the project" has no reference point, so a failure cannot be localized.
  3. Export before you write. The exported block file is the rollback point; asking whether it has unsaved changes distinguishes "still in memory" from "written into the project".

7. Boundaries worth knowing

  • Without a licence, the local gateway is read-only: it can open projects, inspect blocks, export files; write operations are refused. That is a legitimate mode — map the legacy project first, decide later.
  • DSH is a developer preview and its plugin API changes between versions. A plugin that will not install after a client upgrade is an expected outcome, not a bug: check the version range first, and ERESOLVE is usually that.
  • A chat-only sanity check exists: if you have no machine with TIA Portal at hand, configure only the documentation service and ask a version-specific question. A good answer arrives after a tool call; a bad one arrives from memory.

Measurements and error strings come from a real TIA Portal V19 / CPU 1516-3 PN/DP session on Windows; the plugin and gateway are ours. The Chinese original (with the full eight-prompt walkthrough) is at hubwiz.com/blog.

原文:https://www.a8q9.cn/en/article/the-dsh-tia-portal-plugin-wire-an-mcp-gateway-by-talking-then-verify-with-three--0a61ae.html

相关文章