Content
# TIA-MCP · Operating Siemens TIA Portal V18 with Natural Language
> A C# console application that reads/edits/analyzes running **PLC + HMI** projects through **Siemens TIA Portal V18 Openness**.
> **Both command-line subcommands and MCP (stdio) server forms are implemented** - 60 commands packaged as MCP tools for natural language invocation by Claude Code, etc.
> For personal use / single machine / single user. Target project: a single **S7-1200** (about 118 blocks, LAD+SCL mixed, many Chinese names) + 1 **KTP700 Basic** HMI.
**Status: Phase 1-5 completed** (connection → SCL/STL read/write → full language read → graphics/HMI write → troubleshooting suite → MCP packaging).
## Tool List
- **Read/Export**: Read blocks, read variables (including Chinese comments)/UDT, export SCL/STL source code, export SimaticML XML for any block/DB, block metadata.
- **Hardware/Library**: Device list, CPU/module ordering number firmware, rack/slot/module tree (local + distributed IO), subnet/IoSystem/IP, project library/global library.
- **Troubleshooting**: Where-used / dependency / dead code / call tree / called tree / full project cross-reference report (content scanning, V18 without native cross-reference API).
- **Write/Refactor**: Import SCL/SimaticML/UDT, create/delete/modify PLC variables, delete/modify block names/numbers (destructive operations with `--dry-run` + impact warning).
- **Compile/Engineering**: Compile blocks/whole PLC, export whole project to Git, save/archive .zapXX, monitor/force table export, full project annotation/text xlsx batch modification.
- **HMI**: Read + full screen (whole template) replacement + variable add/delete/modify for screens/templates (masters)/variables/connections/text graphics lists (classic KTP700 Basic).
> **Not implemented** (Openness design limitations, not provided by tools): online actual values / force / diagnostic buffer / RUN-STOP / upload / online PN name IP allocation / channel-level diagnostics. Online/download commands require security strategy authorization before addition. See [`docs/COMMAND-MANUAL.md`](docs/COMMAND-MANUAL.md) Appendix B for details.
## Quick Start
### 1. Compile
```powershell
.\build.ps1
```
Output: `bin\Release\net48\TiaMcp.exe` (net48 + x64).
### 2. Open TIA
First, **open TIA Portal V18 and the target project**. After recompiling, the first connection will show an Openness authorization box in the TIA window; click **"Yes"** (no further prompts for the same exe).
### 3a. Command-line Usage
```powershell
.\bin\Release\net48\TiaMcp.exe list
.\bin\Release\net48\TiaMcp.exe export-source FB_Motor
.\bin\Release\net48\TiaMcp.exe find-unused
```
No parameters will print all command groups.
### 3b. MCP Server Usage (with Claude Code)
```powershell
.\bin\Release\net48\TiaMcp.exe mcp # Start stdio JSON-RPC server
```
In Claude Code, add (or place in `.mcp.json`):
```json
{ "mcpServers": { "tia": { "type": "stdio",
"command": "<TiaMcp.exe full path>", "args": ["mcp"] } } }
```
Then use natural language: "List all PLC blocks", "Export FB_Motor to SCL", "Find dead code", "Read HMI variables". Complete connection instructions (prerequisites/limitations/self-test) see **[`docs/MCP-SETUP.md`](docs/MCP-SETUP.md)**.
## Key Technical Decisions
| Item | Choice | Reason |
|---|---|---|
| Target Framework | **net48 + x64** (csproj fixed) | Openness runs on .NET Framework, TIA is 64-bit; AnyCPU/x86 causes BadImageFormatException |
| MCP Protocol Layer | **Handwritten stdio JSON-RPC 2.0** (no official SDK) | Official package requires many modern dependencies on net48; only initialize/tools-list/tools-call needed |
| JSON Library | **.NET built-in `System.Web.Script.Serialization`** | Zero NuGet, self-contained, clone and compile; **no third-party dependencies** |
| Connection Method | Attach to running TIA instance | Real-time observation and modification in the interface |
| Read/Write Architecture | **Dual paths**: SCL/STL through text source, graphics (LAD/FBD/GRAPH) through SimaticML XML block replacement | Openness limitations |
## Architecture / Files
| File | Function |
|---|---|
| `Program.cs` | Entry: register assembly resolver (no Siemens types), then `mcp`→`McpServer` or `Dispatch(argv)` |
| `McpServer.cs` | Handwritten stdio JSON-RPC; 60 commands registered as tools, capture command stdout as tool result, no command modification |
| `OpennessAssemblyResolver.cs` | Redirect `Siemens.*` to PublicAPI\V18 (registry auto-location + fallback path) |
| `TiaSession.cs` | Attach instance → get project → FindPlcs/FindHmis/FindBlock/IsKnowHowProtected |
| `Commands.cs` / `Reads.cs` / `Hardware.cs` / `Library.cs` | PLC read/write/compile / variable UDT / hardware device / library |
| `CrossRef.cs` | Content scanning cross-reference suite |
| `Hmi.cs` / `HmiReads.cs` / `HmiWrites.cs` | HMI probe / read / write (screens + templates + variables + lists) |
| `IoUtil.cs` / `Logger.cs` | %TEMP% temporary file + plaintext verification / file logging |
## ⚠️ Machine-specific: E-SafeNet Transparent Encryption and %TEMP% Relay
This machine has **E-SafeNet transparent encryption** driver installed, which **encrypts files written by the TIA process** (headers contain `E-SafeNet`/`LOCK`): TIA process-written files are encrypted, while our process writes plaintext; **`%TEMP%` is an exemption zone**.
Therefore, **all TIA file I/O goes through `%TEMP%` relay + plaintext verification + immediate deletion**: export = TIA writes to %TEMP% → we read plaintext; import = we write plaintext to %TEMP% → TIA reads. Plaintext disk copies are untrusted (full-disk scanning may later encrypt); deliverables are in-memory text. Switching to a machine without this encryption, the relay is harmless and can be retained.
## Document Index
| Document | Content |
|---|---|
| [`docs/COMMAND-MANUAL.md`](docs/COMMAND-MANUAL.md) | **60 command details**: purpose/input/output examples/exit codes/MCP notes + MCP I/O conventions + Openness limitations |
| [`docs/MCP-SETUP.md`](docs/MCP-SETUP.md) | MCP setup: Claude Code configuration / protocol / prerequisites / limitations / self-test |
| [`docs/AUDIT-2026-06-04.md`](docs/AUDIT-2026-06-04.md) | Instruction set audit: coverage matrix / new command roadmap / manual optimization / defect repair log |
| `PROGRESS.md` / `CLAUDE.md` | Progress status / engineering conventions for AI |
## Known Issues Quick Check
- **BadImageFormatException** → Not an x64 platform.
- **Cannot find Siemens.Engineering** → Openness DLL path incorrect or assembly resolve not registered.
- **No SDKs found** → Used x86 dotnet; use `build.ps1` (x64 path written).
- **Connection no response** → Waiting for TIA Openness authorization box; check TIA window.
- **GetProcesses empty** → TIA not open or not using the same Windows account / account not in Openness group.
