tia-v20-unified-mcp

# Tool List ### Portal And Project / Portal and Project | Tool | English | | --- | --- | | `Connect` | Attach to a running TIA Portal instance or start one. | | `Disconnect` | Dispose the Openness connection. | | `GetState` | Return connection and active project state. | | `GetProject` | List open local projects. | | `OpenProject` | Open a local `.apXX` project; reuses the already-open project when possible. | | `SaveProject` | Save the active local project. | | `SaveAsProject` | Save the active local project to a new directory. | | `CloseProject` | Close the active local project and clear server project state. | `Connect` uses Siemens' standard `TiaPortalProcess.Attach()` flow. When TIA shows the Openness access dialog, the client should keep the same request and server process alive until the engineer approves it. The server does not automatically restart or terminate TIA Portal while authorization is pending. ### Project Structure / Project Structure | Tool | English | | --- | --- | | `GetProjectTree` | Return a tree view of devices, groups, and software containers. | | `GetDevices` | List devices in the active project. | | `GetDeviceInfo` | Inspect one device by project path. | | `GetDeviceItemInfo` | Inspect one device item by project path. | ### PLC Software / PLC Software | Tool | English | | --- | --- | | `GetSoftwareInfo` | Inspect one PLC software object by `softwarePath`. | | `GetSoftwareTree` | Return the PLC block/type hierarchy for a software object. | | `CompileSoftware` | Compile PLC software, with optional safety password support. | ### Blocks / Blocks | Tool | English | | --- | --- | | `GetBlockInfo` | Inspect one block by full block path. | | `GetBlocks` | List blocks by name or regex. | | `GetBlocksWithHierarchy` | Return a structured block hierarchy. | | `ExportBlock` | Export one block to XML. | | `ImportBlock` | Import one XML block with override behavior. | | `ExportBlocks` | Batch export blocks to XML and return items, inconsistent blocks, issues, and metadata. | | `GenerateBlocksFromSource` | Generate PLC blocks from an external `.scl` source file through TIA Openness external sources; normalizes source encoding for Chinese comments. | ### Project Analysis / Project Analysis Read-only tools follow the Siemens Openness XML route: export a timestamped XML snapshot first, then parse the snapshot. Patch tools use the same route, but add backup XML, patched XML, `ImportBlock`, optional compile, optional save, and rollback controls. Read-only analysis snapshots are reused for up to 30 seconds inside one MCP/TIA session. A full-project snapshot can serve later DB, tag-usage, analog, and preview queries. Set `forceRefresh=true` when a fresh export is required. Project switching, imports, source generation, document imports, compile, and Save As invalidate the cache automatically. The analysis layer deliberately returns original engineering structure instead of hard-coding narrow HVAC semantics. The LLM receives DB members, symbols, block/network context, call wiring, and exact references, then performs the project-specific reasoning. | Tool | English | | --- | --- | | `AnalyzeDbMembers` | Export blocks and return complete DB member definitions, including datatype, retain/remanence, and nested names. | | `AnalyzeParameterDbs` | Return parameter DB members and their exact tag usages without inferring business semantics. | | `FindTagUsages` | Find tag usages across exported block networks, including block name and network title. | | `AnalyzeAnalogInputs` | Parse `Convert_IW` calls in analog input blocks and return raw input, scaling, correction, and engineering output. | | `AnalyzeAnalogOutputs` | Parse `Convert_QW` calls in analog output blocks and return engineering input, scaling, and raw output. | | `PreviewAnalogInputPatches` | Dry-run analog input scaling/correction changes and return before/after without modifying XML or TIA. | | `PreviewAnalogOutputPatches` | Dry-run analog output scaling changes and return before/after without modifying XML or TIA. | | `ApplyAnalogInputPatches` | Apply `Convert_IW` changes through export backup -> patch XML -> import -> compile/save/rollback. | | `ApplyAnalogOutputPatches` | Apply `Convert_QW` changes through export backup -> patch XML -> import -> compile/save/rollback. | ### PLC Data Types / PLC Data Types | Tool | English | | --- | --- | | `GetTypeInfo` | Inspect one PLC data type. | | `GetTypes` | List PLC data types by name or regex. | | `ExportType` | Export one PLC data type to XML. | | `ImportType` | Import one XML PLC data type. | | `ExportTypes` | Batch export PLC data types and return structured issue details. | ### V20 SIMATIC SD Documents / V20 SIMATIC SD Documents Use `GenerateBlocksFromSource` for newly written SCL source. The tools below are for SIMATIC SD documents exported by TIA Portal, not hand-written `.scl`. `GenerateBlocksFromSource` passes TIA Portal a UTF-8 BOM temporary source file, which avoids false syntax errors when `.scl` contains comments. | Tool | English | | --- | --- | | `ExportAsDocuments` | Export one supported block as `.s7dcl/.s7res`. | | `ExportBlocksAsDocuments` | Batch export supported blocks as `.s7dcl/.s7res`, preserving per-block issues. | | `ImportFromDocuments` | Import one `.s7dcl/.s7res` document pair. | | `ImportBlocksFromDocuments` | Batch import document blocks from `.s7dcl` files with warning and issue reporting. | ## Recommended Agent Workflow / Recommended Agent Workflow 1. `Connect`. 2. `OpenProject`. 3. `GetProjectTree`. 4. `GetSoftwareTree`. 5. Use `AnalyzeDbMembers`, `AnalyzeParameterDbs`, `AnalyzeAnalogInputs`, `AnalyzeAnalogOutputs`, and `FindTagUsages` to build a structured snapshot. 6. Use `PreviewAnalogInputPatches` or `PreviewAnalogOutputPatches` for dry-run before any import/write action. 7. Check `snapshotPath`, `snapshotReused`, `Issues`, `Meta.partial`, and before/after values; use `forceRefresh=true` after manual TIA edits. 8. For analog batches, use `ApplyAnalogInputPatches` or `ApplyAnalogOutputPatches` only after the preview is unambiguous; keep `apply=false` until the write is intentional. 9. Keep `rollbackOnFailure=true`; use `rollbackAfterCompile=true` for field-path validation without leaving edits behind. 10. `SaveProject` only when changes should persist. 11. `CloseProject` and `Disconnect` when finished. ### Field Engineer Example / Field Engineer Example For one room or one AHU, a practical agent session normally keeps one Portal connection and performs several related checks together: 1. Locate the temperature/RH raw inputs, engineering outputs, ranges, and correction values. 2. Trace the values into control logic, PID parameters, upper/lower alarms, HMI data, and actuator outputs. 3. Preview a batch correction or range change and reject no-match or ambiguous selectors. 4. Save As a field-test copy, import once, compile once, and either keep the verified result or roll it back. The server should not close and reopen TIA Portal between these steps. Snapshot reuse and transaction-style patch tools are designed to reduce repeated exports, repeated attaches, and unnecessary Portal resource use. ## Requirements / Requirements | English | | --- | | Windows machine. | | Siemens TIA Portal V20 installed. | | .NET Framework 4.8 developer/runtime support. | | Environment variable `TiaPortalLocation=C:\Program Files\Siemens\Automation\Portal V20`. | | Current Windows user in `Siemens TIA Openness`. | ## Build / Build ```powershell dotnet restore .\server\TiaMcpServer.csproj dotnet build .\server\TiaMcpServer.csproj -c Release ``` Expected executable: ```text server\bin\Release\net48\TiaV20UnifiedMcpServer.exe ``` Run the offline readiness check: ```powershell .\scripts\Test-OfflineReadiness.ps1 -BuildServer ``` ## MCP Client Configuration / MCP Client Configuration Example server entry for an MCP stdio client: ```json { "name": "tia-v20-unified-mcp", "command": "C:\\path\\to\\TiaV20UnifiedMcpServer.exe", "args": [ "--tia-major-version", "20", "--logging", "stderr", "--transport", "stdio" ], "env": {} } ``` ## Verification Validated on a TIA Portal V20 machine with the provided local test project: The internal handoff package should not include Siemens/TIA Portal paid software, Openness DLLs, generated build output, or local TIA project archives such as `TestProject1.zap20`. Offline XML transaction tests: ```powershell dotnet test .\tests\TiaMcpServer.Unit\TiaMcpServer.Unit.csproj -c Release ``` Latest V20 field validation used a `SaveAsProject` copy of a real HVAC project: - 66 `Convert_IW` input channels and 26 `Convert_QW` output channels analyzed. - Exact, ambiguous, and invalid patch guards verified. - Input patch import, compile, rollback import, and rollback compile succeeded. - Output patch import, compile, rollback import, and rollback compile succeeded. - Two input channels were patched in one XML import and one compile transaction, then restored. - The original `.ap20` SHA-256 remained unchanged. ```powershell dotnet test .\tests\TiaMcpServer.Test\TiaMcpServer.Test.csproj -c Release --no-build ``` Latest local result after removing Multiuser/session coverage: ```text 77 passed, 0 failed, 0 skipped ``` ## Tool List | Path | English | | --- | --- | | `server/` | .NET Framework 4.8 MCP server and Siemens Openness wrapper. | | `tests/` | MSTest integration tests for V20 local project workflows. | | `docs/` | Architecture notes, tool matrix, and verification notes. | | `scripts/` | Local readiness checks. | ## Internal Handoff Boundary | English | | --- | | Share source code, docs, scripts, package manifests, and non-proprietary assets only. | | Do not include Siemens/TIA Portal paid software, installer files, Openness DLLs, or generated server binaries unless your company license and delivery process explicitly allow it. | | Do not include real project archives or exports, including `.apXX`, `.zapXX`, `.alsXX`, `.s7p`, `.s7dcl`, and `.s7res`. | | Do not include private authentication files, certificates, keys, `.env` files, local MCP configuration, or machine-specific credentials. | | Integration-test assets are local-only and must be recreated by each developer on their own machine. | ## License This repository keeps the upstream MIT license notice in `LICENSE.upstream-heilingbrunner.txt`.