Tiaportal MCP

TIA Portal MCP — Single Skill

This is the operating skill for TIA Portal MCP automation. The companion plugin lives at tools/tiaportal-mcp/. It exposes on the order of ~201 MCP tools (lite profile ~43; exact runtime set: call tools/list on the running server) covering project, hardware, PLC, HMI, and online operations.

0. Always start here

1. Call Bootstrap                        ← returns env, project state, next step
2. Follow RecommendedNextTool            ← e.g. Connect, AttachToOpenProject
3. Call GetProjectTree                   ← resolve real paths (PLC_1, HMI_RT_1)
4. Read-before-write loop                ← inspect, smallest change, compile, save

交付包内最短路径（仅读包内文件时）
根目录 README.md（三步上手）→ scripts/Validate-Bundle.ps1（脱机校验）→ 用 cursor-mcp.example.json 把 command 指到包内 TiaMcpServer.exe → 执行顺序见 docs/full-project-generation-runbook.md 与 templates/project-blueprints/full_plc_hmi_project.json。

Never guess paths. Never invent SCL/LAD XML. If a tool exists for the task, use it; otherwise inspect with DescribeObject/DescribeService first, then call InvokeObject/InvokeService.

0.1 弱模型 / 新手：你一辈子只需要这 15 个工具（其余的先忽略）

This server exposes ~190 tools. You do NOT need most of them. A small or non-expert model should pick only from this whitelist and ignore everything else unless one of these tools' output explicitly tells you to call another:

铁律(弱模型尤其要守): ① 永远先 Bootstrap(或装不上时先 Doctor)，照 recommendedNextTool 走。② 路径只从 GetProjectTree 拿，绝不自己编。③ 写操作前先 dryRun=true。④ 收尾必须 CompileAndDiagnosePlc(0 错) + SaveProject。⑤ 拿不准 参数名时，照本表/§8 的"精确参数名"抄，不要猜。HMI 美化看 §12，库复用看 §15。

降门槛三件套(已内置，弱模型友好):

• Lite 工具档位 — 启动 server 时设环境变量 TIA_MCP_PROFILE=lite，tools/list 只暴露 ~42 个 L0/L1 核心工具(而非全部 ~200)，弱模型不会在工具海里选错，VS Code 的 128 工具上限也不再爆。默认仍是 full；要全量工具就别设这个变量。一键写入宿主配置： tia config --lite。(v2.2.8 实测：full=201 工具含 L2，lite=43 工具无 L2。)
• 参数容错 — softwarePath 现在容忍多余空格/大小写，单 PLC 工程或唯一匹配时 传"PLC"也能自动认到 PLC_1；找不到时报错会列出可用 PLC 路径。少数易错工具 接受别名(tableJson↔tagTableJson、screenJson↔designJson、 blockJson↔fcBlockJson、name↔projectName)。即便如此，优先传准确值。
• 一键自检自修 — 见上表 Doctor。

0.5 Fastest path — generate a whole project in ONE call (ScaffoldProject)

When the user asks to create/generate a complete project (PLC + HMI, "做一个启停/电机/控制项目"), do not hand-orchestrate the 20-step runbook. Call ScaffoldProject once with a single JSON spec; it auto-connects, creates the project, adds PLC (+optional Unified HMI) hardware, builds UDTs/DBs/tag tables, imports SCL + LAD blocks, compiles, sets up the HMI connection/screens/tags, and saves — returning a per-step report with compile error counts. This is one model turn instead of twenty, and far less error-prone.

Ready-made specs (copy, then replace __BUNDLE__ with the bundle root absolute path; all blocks/HMI are verified to compile with 0 errors):

templates/project-blueprints/scaffold_spec_start_stop.json   启停控制 (PLC+HMI)
templates/project-blueprints/scaffold_spec_motor.json        电机控制 (启停闭锁 + 速度标定 + HMI)

Minimal spec (everything else has defaults — only projectName is required):

{ "projectName": "MyProj",
  "plcName": "PLC_1", "plcFamily": "S7-1500",
  "hmiName": "HMI_1", "hmiSoftwarePath": "HMI_RT_1",
  "udt": [ { /* same json as PlcBuildAndImport kind=udt */ } ],
  "globalDb": [ { /* kind=globaldb json */ } ],
  "tagTable": [ { /* kind=tagtable json */ } ],
  "sclSourceFiles": [ "C:\\bundle\\templates\\plc\\scl-examples\\FB_BasicLatch.scl" ],
  "ladDocs": [ { "importPath": "C:\\bundle\\...\\skill\\lad-cookbook", "name": "MCPVerify_FC_LAD" } ],
  "hmiScreens": [ { "screenName": "主画面", "width": 800, "height": 480, "designJson": { /* §6.3 schema */ } } ],
  "hmiTags": [ { "tagTableName": "Default tag table", "tagName": "Tag_Run", "hmiDataType": "Bool", "address": "%DB100.DBX0.0" } ],
  "compile": true, "save": true }

Notes:

• Omit hmiName to skip all HMI. Omit any of udt/globalDb/tagTable/sclSourceFiles/ladDocs/hmiScreens/hmiTags to skip that part.
• udt/globalDb/tagTable items are the exact json shapes from §6.2 (what PlcBuildAndImport accepts).
• designJson is the §6.3 Unified HMI schema. Size the screen to the panel's native resolution (WinCC Unified PC default 800×480) or it will be clipped.
• HMI tags: use an absolute PLC address (%DB100.DBX0.0, %MD10) so the binding read-back verifies.
• Critical-step failures (connect/createProject/PLC device) abort and throw; per-element failures are collected in the returned steps so you can see exactly what to fix and re-run.
• For per-session fast connects, keep a warm headless instance running (_prewarm_tia.py); see §0.

Only fall back to the manual runbook (docs/full-project-generation-runbook.md) when the user needs something ScaffoldProject does not cover.

1. Tool layers

The Description of every tool starts with one of three layer tags:

Core L0/L1 set:

L0  Bootstrap, GetState, RunCapabilitySelfTest, RunOnlineMonitoringSafetySelfTest,
    GenerateAcceptanceReport, GenerateErrorReport
L1  Connect, Disconnect, AttachToOpenProject, OpenProject, CreateProject,
    ScaffoldProject, SaveProject, CloseProject, GetProjectTree, GetSoftwareTree, GetSoftwareInfo,
    PlcBuildAndImport, CompileSoftware, CompileAndDiagnosePlc,
    DownloadToPlc, CheckDownloadReadiness, GoOnline, GoOffline, GetOnlineState,
    EnsureOpennessUserGroup, ListPortalProcessProjects, GetProject,
    GetDevices, AddDeviceWithFallback, SearchHardwareCatalog,
    ImportBlock, ImportType, ImportPlcTagTable,
    ConnectDeviceNodesToProfinetSubnet, ValidateAutomationContext

2. Connecting an AI client to the MCP server

stdio (Claude Desktop, Cursor, VS Code MCP)

{
  "mcpServers": {
    "tia-portal": {
      "command": "C:\\path\\to\\TiaMcpServer.exe",
      "args": []
    }
  }
}

HTTP (any client that speaks JSON-RPC)

TiaMcpServer.exe --transport http --http-prefix http://127.0.0.1:8765/ --http-api-key <secret>

Endpoints:

Auth (when --http-api-key is set): either header works — pick whichever your client supports:

Authorization: Bearer <secret>
X-API-Key: <secret>

Set Accept: text/event-stream to get the response wrapped as a single SSE message event (for spec-compliant clients). Otherwise the response is plain JSON.

Mcp-Session-Id is generated on the first call and echoed back; subsequent calls may include it for client-side correlation. State is not isolated across sessions because TIA Portal itself is process-wide.

调用方式怎么选（避免踩坑）

3. Read-before-write workflow (the only one that matters)

GetProjectTree                       resolve PLC/HMI paths
ExportBlock|GetBlockInfo|...         inspect what already exists
PlcBuildAndImport (kind=fc|udt|...)  smallest safe change
CompileSoftware                      must end with errors=0 warnings=0
SaveProject                          persist to disk

PlcBuildAndImport is the preferred entry for declarative PLC objects (UDT, tag table, GlobalDB, FC, FB) — it generates Openness XML and imports in one call. Use the lower-level ImportBlock/ImportType/ImportPlcTagTable only when you already have hand-crafted XML.

4. What this MCP cannot do (V21 PublicAPI limits)

These have NO Openness API — do not try to invent reflection workarounds:

• Read or change CPU operating mode (RUN/STOP/STARTUP) → use OPC UA
• Read CPU fault/diagnostic buffer → use OPC UA
• ClearForces / Unforce / per-block selective download
• Trigger Safety F-CPU compile (must be done in TIA UI manually)

Force/Watch table tools edit the project-side definition; values become effective only after the project is online and the table trigger fires.

Full list (this bundle): 手册/openness-limitations.md (bundle root: same folder as README.md).

5. Encoding & PowerShell traps (script drivers only)

• The server itself sets Console.InputEncoding = Console.OutputEncoding = UTF-8 on startup (since v0.0.27 + the 2026-05-11 patch). Without that, Chinese project names / device names / commentZhCn payloads become ??? over stdio. If you fork an older build, you must add it yourself.

• Generated .scl external sources and any Chinese text destined for TIA import must be UTF-8 with BOM.

• PowerShell 5.1 reads .ps1 as the system code page (GBK on zh-CN Windows) unless the file is UTF-8-with-BOM. Any path containing Chinese (e.g. Chinese characters) breaks Process.Start if the script itself is bare UTF-8.

• .NET Framework 4.8 does NOT have ProcessStartInfo.StandardInputEncoding (Core-only API). To send UTF-8 to a child server's stdin from PowerShell:

  $proc = [System.Diagnostics.Process]::Start($psi)
  $stdinUtf8 = New-Object System.IO.StreamWriter(
      $proc.StandardInput.BaseStream,
      (New-Object System.Text.UTF8Encoding($false)))
  $stdinUtf8.AutoFlush = $true
  $stdinUtf8.WriteLine($jsonRpcLine)   # use this; do NOT use $proc.StandardInput
  

• Reading stdio responses: cache the pending ReadLineAsync task between iterations. Calling ReadLineAsync twice on the same stream before the first one completes throws "流正在由其上的前一操作使用".

  if ($null -eq $script:pending) { $script:pending = $proc.StandardOutput.ReadLineAsync() }
  if (-not $script:pending.Wait($remainMs)) { continue }
  $line = $script:pending.Result; $script:pending = $null
  

• Tool failures often surface as result.isError = true with content[0].text = "An error occurred invoking 'X'" rather than as a JSON-RPC error. Check both shapes; the real exception text is on stderr.

• Don't read tool-call response text via regex — the server JSON-encodes Chinese as \uXXXX. Always ConvertFrom-Json the text field first, then read named properties (.items[0].name, .tree, ...).

6. Bundle-only docs + copy-paste JSON for PlcBuildAndImport / Unified HMI

Paths below are relative to the delivery bundle root (the folder that contains README.md, 手册/, and tools/).

6.1 Authoritative files shipped in this bundle

The static files are for planning and parser grounding; run tools/list on the live MCP server for the authoritative runtime roster. There is no bundled Siemens STEP7/WinCC manual tree.

6.2 PlcBuildAndImport — minimal json shapes (always dryRun=true first)

Pass json as a string (escape quotes in MCP args). Replace softwarePath / group paths with values from GetProjectTree.

kind=udt

{"name":"UDT_MCP_Demo","members":[{"name":"Speed","datatype":"Int","externalWritable":false}]}

kind=tagtable

{"tableName":"MCP_DemoTags","tags":[{"name":"DemoRun","dataTypeName":"Bool","logicalAddress":"%M0.0"}]}

kind=globaldb

{"dbName":"GDB_MCP_Demo","dbNumber":1,"staticMembers":[{"name":"Counter","datatype":"Int","startValue":"0"}]}

kind=fc (ST body from structuredText.operations; op includes if, elsif, else, endif, assignment, line, …)

{
  "blockName":"FC_MCP_Demo",
  "blockNumber":1,
  "inputs":[{"name":"InRun","datatype":"Bool"}],
  "outputs":[{"name":"OutOk","datatype":"Bool"}],
  "structuredText":{"operations":[{"op":"assignment","target":"OutOk","literalValue":"TRUE"}]}
}

kind=fb

{
  "blockName":"FB_MCP_Demo",
  "blockNumber":2,
  "inputs":[{"name":"En","datatype":"Bool"}],
  "outputs":[{"name":"Busy","datatype":"Bool"}],
  "statics":[],
  "structuredText":{"operations":[{"op":"assignment","target":"Busy","literalValue":"FALSE"}]}
}

6.3 Unified HMI — minimal designJson for ApplyUnifiedHmiScreenDesignJson

Keys are lowercase. Colors: ARGB hex strings like 0xAARRGGBB. Call EnsureUnifiedHmiScreen before apply. Button bit actions: EnsureUnifiedHmiButtonAction with eventType Down / Up / Tapped ( Pressed / Released are wrong ). Full recipe + schema: §12 below.

{
  "screen":{"BackColor":"0xFFF8FAFC"},
  "items":[
    {"type":"Rectangle","name":"Panel","left":24,"top":80,"width":400,"height":200,"properties":{"BackColor":"0xFFFFFFFF","BorderWidth":1}},
    {"type":"Text","name":"Lbl","left":40,"top":100,"width":200,"height":28,"text":"Demo","font":{"Size":16}},
    {"type":"Button","name":"StartBtn","left":40,"top":160,"width":120,"height":44,"text":"Start"},
    {"type":"IOField","name":"SpFld","left":180,"top":160,"width":100,"height":40}
  ]
}

7. Common end-to-end shapes

Build a minimal new project

Bootstrap → Connect → CreateProject(<dir>, <name>_<timestamp>)
→ AddDeviceWithFallback(CPU)
→ AddHardwareCatalogDeviceWithProbe(HMI)       (optional)
→ ConnectDeviceNodesToProfinetSubnet           (optional)
→ PlcBuildAndImport(kind=tagtable, ...)
→ PlcBuildAndImport(kind=globaldb, ...)
→ PlcBuildAndImport(kind=fc|fb, ...)           (one per logic unit)
→ CompileSoftware                              (must be 0/0)
→ SaveProject → Disconnect

Build a complete example project (not a 2-tag toy)

When the user asks for a "demo / 示例 / example project", the minimal recipe above produces something that looks empty. A good example must include, at minimum:

• PLC: ≥1 UDT (e.g. UDT_Motor), a global DB instanced from it, a tag table with named I/O (not just %I0.0), and ≥2 logic blocks (e.g. an FB with the control logic + an FC or OB1 that calls it). Reuse the verified blocks in demo-assets/plc/ (UDT_Motor, FB_StartStop, FC_StartStop, Main).
• HMI: a styled Main screen built with the §12 aesthetic recipe (title bar + status cards + buttons + IOField + indicator lamps) — not a bare button or two. Do not stop at EnsureStartStopUnifiedHmi; that is a wiring shortcut, not a finished screen. Always follow it with ApplyUnifiedHmiScreenDesignJson (§12).
• Binding: every HMI tag bound to a real PLC tag through the connection (below).
• Compile to 0/0 and SaveProject before declaring done.

Standard HMI variable connection & driver (do this, every time)

The non-standard binding users complain about comes from skipping these:

1. One connection, correct driver. EnsureUnifiedHmiConnection (Unified) / HMI_Connection_1 (Classic) auto-selects the PLC driver from the CPU TypeIdentifier (S7-1200/1500 vs 300/400). Never hand-name a driver; never point two tag tables at different ad-hoc connection names.
2. Symbolic binding, not absolute. Bind each HMI tag to a named PLC tag (ControllerTag = Conveyor.Start, AddressAccessMode=Symbolic) — never to a raw %DB1.DBX0.0. Absolute addresses break on PLC recompile/reorder.
3. Acquisition cycle 100 ms for interactive controls; slower (1 s) for read-only displays — don't leave everything on the default.
4. The PLC tag/DB member must exist before the HMI tag binds to it, or the binding silently drops. Build PLC side first, then HMI.

Deploy to a real CPU

Bootstrap → AttachToOpenProject
→ CompileSoftware
→ CheckDownloadReadiness
→ DownloadToPlc(keepActualValues=true)
→ GetOnlineState → SaveProject

Watch/Force values

Bootstrap → AttachToOpenProject → GoOnline
→ SetForceTableEntry(address, value)           force, persistent until cleared
→ SetWatchTableModifyValue(address, value)     one-shot modify
→ GoOffline

For more scenarios (alarms, OPC UA, multi-language text, Unified HMI pages) see 手册/TIA_NL_INTENT_RECIPES.md (bundle root).

8. Frequently used tools — exact parameter names

The table below lists exact parameter names that commonly trip parsers. When in doubt, confirm with tools/list / Bootstrap on your build.

Attach-mode workflow (no pollution, preferred when TIA already has a project open)

Bootstrap                                     ← env + recommendedNextTool
Connect                                       ← may need Openness UI click on first call
GetProject  →  items[0].name                  ← internal Project.Name; TIA window title may differ
AttachToOpenProject(projectName=<that name>)  ← reuse existing project
GetProjectTree                                ← never guess paths
                                               regex 'PlcSoftware:\s*([^\s\[]+)' → all PLC softwarePaths
GetDevices                                    ← returns station containers, not CPUs
                                               → use GetProjectTree to find real PLC names
GetSoftwareTree / GetBlocks / GetSoftwareInfo ← inspect
PlcBuildAndImport(dryRun=true)                ← validate XML without modifying project
GetOnlineState / CheckDownloadReadiness       ← read-only diagnostics
Disconnect

Real-write on a Chinese-named device (verified 2026-05-11 against 安全PLC)

Connect
GetProject                                     → "江夏测试项目V21-260511"
AttachToOpenProject(projectName="江夏测试项目V21-260511")
GetProjectTree                                → discover "PlcSoftware: 安全PLC"
PlcBuildAndImport(softwarePath="安全PLC", kind="tagtable", json=…, dryRun=false) → 10s, ok
PlcBuildAndImport(softwarePath="安全PLC", kind="globaldb", json=…, dryRun=false) → 5s, ok
PlcBuildAndImport(softwarePath="安全PLC", kind="fc",       json=…, dryRun=false) → 5s, ok
GetBlocks(softwarePath="安全PLC", namePattern="MCPVerify_*") → confirms imported blocks
CompileSoftware(softwarePath="安全PLC")        → 18s, errorCount=0 (warnings ok)
CheckDownloadReadiness / GetOnlineState        → ready=true / state=Offline
SaveProject → Disconnect

Use a unique prefix (MCPVerify_, MCP_, etc.) for any object you write into a real shared project — the user can find and delete them in TIA UI later.

Common parameter-name traps

PowerShell-side: call shape that works with tools/call:

$resp = Send-Request 'tools/call' @{ name='PlcBuildAndImport'; arguments=@{
    softwarePath='PLC_1'; kind='tagtable'; dryRun=$true
    json='{"tableName":"DefaultTagTable","tags":[{"name":"Start","dataTypeName":"Bool","logicalAddress":"%I0.0"}]}'
} } 30000

9. Generating LAD — prefer S7DCL text over FlgNet XML

Decision rule (read this first):

There is no MCP tool that builds contact/coil/compare FlgNet XML (LadNetworkBuilder is not wired up). So for normal ladder, write .s7dcl — do not hand-roll FlgNet XML.

9a. LAD via S7DCL (PREFERRED, verified V21 round-trip)

Author two paired files, both UTF-8 with BOM:

• Name.s7dcl — block declaration + LAD networks
• Name.s7res — MLC_* text IDs → localized strings (this is where Chinese comments/titles live)

Verified references — copy these, change names + logic:

skill/lad-cookbook/MCPVerify_FC_LAD.s7dcl    + .s7res  (FC: 串联/并联/SR/比较/Move/Add)
skill/lad-cookbook/MCPVerify_FB_LAD_v3.s7dcl + .s7res  (FB: 定时器放 Static)
skill/lad-cookbook/MCPVerify_Mixed_LADSCL.s7dcl + .s7res  (FB: LAD+SCL 混编 — 互锁/比较+定时/SCL算术/边沿,
                                                          全部 import-verified 形式; 2026-06-11 编译0错)

Grammar (distilled from the verified sample):

{ S7_BlockComment := "MLC_548"; S7_BlockNumber := "901";
  S7_BlockTitle := "MLC_4Vm"; S7_Optimized := "TRUE";
  S7_PreferredLanguage := "LAD"; S7_Version := "0.1" }
FUNCTION "MCPVerify_FC_LAD" : Void
    VAR_INPUT  "A" : Bool; SET : Bool; VAL : Int; END_VAR
    VAR_OUTPUT OUT_AND : Bool; OUT_SR : Bool; DST : Int; END_VAR

    { S7_Language := "LAD"; S7_NetworkComment := "MLC_4X9"; S7_NetworkTitle := "MLC_3fA" }
    NETWORK
        RUNG wire#powerrail                       -- series AND
            Contact( #"A" ) Contact( #"B" ) Coil( #OUT_AND )
        END_RUNG
    END_NETWORK

    NETWORK                                        -- parallel OR via wire#w1
        RUNG wire#powerrail Contact( #"A" ) wire#w1 Coil( #OUT_OR ) END_RUNG
        RUNG wire#powerrail Contact( #"B" )        END_RUNG wire#w1
    END_NETWORK

    NETWORK RUNG wire#powerrail Contact( #SET )   S_Coil( #OUT_SR ) END_RUNG END_NETWORK
    NETWORK RUNG wire#powerrail Contact( #RESET ) R_Coil( #OUT_SR ) END_RUNG END_NETWORK

    NETWORK                                        -- compare: VAL > 100
        RUNG wire#powerrail
            { S7_Templates := "SrcType := Int" }
            GT_Contact( in1 := #VAL, in2 := 100 ) Coil( #OUT_GT )
        END_RUNG
    END_NETWORK

    NETWORK RUNG wire#powerrail Move( in := 42, out1 => #DST ) END_RUNG END_NETWORK
    NETWORK
        RUNG wire#powerrail
            { S7_Templates := "SrcType := Int" }
            Add( in1 := #V1, in2 := #V2, out => #SUM )
        END_RUNG
    END_NETWORK
END_FUNCTION

Element vocabulary: Contact/Coil/S_Coil/R_Coil, parallel branches joined by a wire#wN label, GT_Contact/LT_Contact/… + { S7_Templates := "SrcType := Int" }, Move( in:=, out1=> ), Add/Sub/Mul/Div( in1:=, in2:=, out=> ). .s7res id: values must match every MLC_* referenced in .s7dcl. For instructions not shown here (常闭/negated contact, edges, timers, Calc…), export a real block that uses them with ExportBlocksAsDocuments and copy the exact .s7dcl syntax — BUT beware: the export form of several instructions does NOT re-import (export grammar ≠ import grammar). Verified 2026-06-11: Gt/Lt/Ne/Eq{ SrcType }( IN1, IN2 ), PBox(...), and Move{ Card:=1; DisableENO:=TRUE }( IN, OUT1 ) (all from real-block exports) fail ImportFromDocuments with a generic "Failed importing". The import-verified forms are below.

Real-block verified vocabulary — IMPORT forms (江夏5T车, hand-authored blocks, compile 0 errors, 2026-06-11). ⚠️ author the import form (left), never the export form (right):

Neg is not import-verified — keep negate networks in SCL.

Branch (wire) model — wire#wN is a junction: tap out (RUNG wire#wN … = parallel branch from that point) + join in (… END_RUNG wire#wN = OR back into junction wN).

Titles must be MLC_* refs (in .s7res) or omitted — inline literal titles (S7_NetworkTitle := "中文") fail on import; strip or convert to MLC_*.

Mixed LAD+SCL (verified V21): a block with S7_PreferredLanguage := "LAD" can interleave { S7_Language := "SCL" } NETWORK <scl statements> END_NETWORK with LAD networks. A pure-SCL block cannot hold LAD networks — author in LAD when you need the mix. See cookbook MCPVerify_Mixed_LADSCL.s7dcl.

Per-network LAD/SCL judgment — author LAD for interlock / limit / brake-timer / workstep-trigger / indicator logic (electricians read power-flow); keep SCL for arithmetic/scaling, multi-param FC/FB calls, state machines, comms, complex condition aggregation. Do not force LAD. (Validated on 江夏5T车: 02/03/04/09 + A3_2/3/5 reauthored mixed, 0 errors; A0_1/A4_1/comms kept SCL.)

Import (verified MCP workflow, 2026-06-11):

# 1) write Name.s7dcl + Name.s7res, BOTH UTF-8 *with* BOM, in one dir
ImportFromDocuments(softwarePath="<plc>", groupPath="<group path or empty>",
                    importPath="<dir>", fileNameWithoutExtension="<BlockName>",
                    importOption="Override")   # Override replaces same-name block & keeps its number
#   batch: ImportBlocksFromDocuments(softwarePath=, groupPath=, importPath=, regexName="")
CompileAndDiagnosePlc(softwarePath="<plc>")     ← errorCount must be 0

• .s7res must be present even when titles omitted (minimal: one MLC_x with zh-CN: + en-US:).
• ImportBlockFromScl / ImportBlocksFromScl are thin aliases of the two import tools above.

Boundary (known TIA limitation): importing LAD from SD documents can fail unless every .s7res item also has an en-US tag, not only zh-CN. The bundled samples round-tripped on a V21 zh-CN machine with zh-CN only, but if ImportBlocksFromDocuments fails on a LAD block, add an en-US: line beside each zh-CN: in the .s7res and retry. (See README "Known Limitations".)

9b. LAD via FlgNet XML (fallback — FC-call tool, or last-resort hand edit)

LAD blocks live in <FlgNet xmlns="http://.../FlgNet/v5"> with two collections: Parts (operands + instructions) and Wires (pin-to-pin energy flow).

A 7-network reference FC that imports cleanly (errorCount=0) and covers the core instruction set is at:

tools/tiaportal-mcp/skill/lad-cookbook/MCPVerify_FC_LAD.xml

It exercises:

Verified Part Name registry (more exist; these are the ones live-tested):

Contact          常开触点 (add <Negated Name="operand"/> for 常闭)
Coil / SCoil / RCoil   线圈 / 置位 / 复位
O                并联 OR-box (TemplateValue Name="Card" = inputs count)
PBox / NBox      上升沿 / 下降沿
Gt / Lt / Eq / Ne / Ge / Le   比较 (TemplateValue SrcType=Int|DInt|Real|Word|...)
Add / Sub / Mul / Div         算术 (SrcType + Card templates)
Move             传送 (Card=1 normally)
TON / TOF / TP   IEC 定时器 (require <Instance Scope="LocalVariable|GlobalVariable" UId="…"><Component Name="..."/></Instance>; only inside FB or with explicit IDB)
Calc             表达式块 (<Equation>...</Equation> + Card + SrcType)
Serialize / Deserialize / SCATTER / GATHER   字节级转换

Connection reference (Wires rules):

<Wire UId="…">
  <Powerrail/>                左端母线（能流入口）
  <NameCon UId="P" Name="…"/> 接到 Part P 的命名引脚
  <NameCon UId="P2" Name="…"/> 多个 NameCon = 并联同时驱动多个 Part
</Wire>

<Wire><IdentCon UId="V"/><NameCon UId="P" Name="operand"/></Wire>
                                     变量/字面量 V 接到 P 的 operand/in/...
<Wire><NameCon UId="P1" Name="out"/><NameCon UId="P2" Name="in"/></Wire>
                                     P1.out 串联到 P2.in

LAD pitfalls (these all bit me — read once, save hours)

1. UId inside <FlgNet> MUST be decimal xs:int, NOT hex. Block-level ID attributes ARE hex strings ("A", "B", "10", "1A"...) and they live in a separate namespace. Mixing them gives the cryptic Simatic ML error: UId 属性无效 - 类型 …XMLSchema:int 的值 "2A" 无效.
2. Strip every <!-- --> XML comment before import — Openness rejects them.
3. Escape & < > in any <Text>/comment — TIA reports 分析 EntityName 时出错。 第 N.
4. The ProgrammingLanguage element appears twice: once at block level (<SW.Blocks.FC>/AttributeList/ProgrammingLanguage>LAD) and once per CompileUnit (AttributeList/ProgrammingLanguage>LAD). Mixing SCL and LAD networks is allowed if you set the per-CompileUnit value accordingly.
5. Importing Contact + Coil + Compare/Move/Add to a safety PLC standard block group works — these are standard instructions; safety F-FCs need different builders we don't ship yet.
6. After ImportBlock, server now surfaces the real Openness exception chain (Portal.cs UnwrapImportError, since 2026-05-11). Don't reinterpret "Import failed" — read everything after the colon.

To create a new LAD FC, copy MCPVerify_FC_LAD.xml, change Name, Number, Interface/Sections, and rebuild networks. Then:

ImportBlock(softwarePath="<plc>", groupPath="", importPath="<your.xml>")
CompileSoftware(softwarePath="<plc>")        ← errorCount must be 0

10. SCL via DSL (verified 2026-05-11)

PlcBuildAndImport(kind=fc, json={…structuredText.operations}) is the supported DSL. Verified ops: assignment, if, else, endif, line, token, blank, newline, symbol, local, global, literal.

{
  "blockName": "MyFc", "blockNumber": 902,
  "inputs":  [{"name":"Reset","datatype":"Bool"}, {"name":"Speed","datatype":"Real"}],
  "outputs": [{"name":"Out","datatype":"Real"}, {"name":"Mode","datatype":"Int"}],
  "structuredText": { "operations": [
    {"op":"assignment","target":"Out","literalValue":"0.0"},
    {"op":"if","condition":"Reset"},
      {"op":"assignment","target":"Out","literalValue":"0.0","indent":1},
      {"op":"assignment","target":"Mode","literalValue":"0","indent":1},
    {"op":"else"},
      {"op":"line","indent":1,"items":[
        {"sym":"Out"},{"token":":="},{"sym":"Speed"},{"token":"*"},{"lit":"1.5"}
      ]},
      {"op":"assignment","target":"Mode","literalValue":"1","indent":1},
    {"op":"endif"}
  ]}
}

SCL DSL limits (known)

• if/elsif condition and assignment source accept a single variable name only — NOT expressions like Mode = 1, Setpoint - Actual, Disable OR FaultLatch, ABS(x), or the literals TRUE/FALSE. The builder now hard-errors at build/dryRun on such input (e.g. SCL 局部符号非法："RawMax <> RawMin") instead of silently emitting a variable named after the whole expression — which used to slip through dryRun and only blow up at TIA compile as Tag #"…" not defined.
• For multi-variable conditions, fall back to op:"line" (free-form token list, but it always appends ; and newline, so it can't emit standalone IF cond THEN headers).
• for, while, case, return, exit, continue, repeat are NOT supported by the DSL. Preferred path: write a native .scl and import via ImportPlcExternalSource + GenerateBlocksFromExternalSource (§14) — see templates/plc/scl-examples/*.scl for ready FC/FB examples. (Hand-writing the <StructuredText> token AST also works but is far more error-prone.)
• String/WString outputs may compile-error in some safety standard groups; test with dryRun=true first.

11. LAD v2 — extended instructions (verified 2026-05-11 against 安全PLC, errorCount=0)

A second cookbook FC adds 10 more instructions on top of §9. Imports cleanly and compiles with errorCount=0 on Safety PLC standard side:

tools/tiaportal-mcp/skill/lad-cookbook/MCPVerify_FC_LAD_v2.xml   ← FC 902

Combined with §9, the verified native-LAD instruction set is: contacts (NO/NC) · S/R coils · OR-box · Compare (Eq/Ne/Lt/Gt/Le/Ge) · Math (Add/Sub/Mul/Div/Mod) · Convert · Move.

Import skill/lad-cookbook/MCPVerify_FC_LAD.xml via ImportBlock and compile; the FC encodes the v2 instruction sweep (8 networks).

LAD v3 — timers must not live in FC Temp on F-CPU; use FB Static or DB

Rule (F-CPU / 安全 PLC): TON / TOF / TP IEC timer instances must not be declared in an FC Temp section (not allowed → compile errors). Valid options: (1) TON_TIME in FB → Static (with SetPoint on the static member when the export shows it — see Speed_Ctrl.xml), (2) timer in a global DB and Instance Scope="GlobalVariable" in LAD (see 07-操作选择.xml), (3) author in TIA and ExportBlock.

Repo layout:

Stage both XML files to a temp folder, import FC then FB with ImportBlock into the PLC software path from GetProjectTree, then CompileSoftware until errorCount=0.

PBox wiring: same operand for contact and bit needs two Access entries with **d

…(truncated)