/tia-portal-mcp

name: tia-portal-mcp
description: >
  Use when the TIA Portal MCP server is available for focused, guarded project
  reads and writes. Use TIA Openness skills for complex multi-step automation.
license: MIT

tia-portal-mcp

Scope

Use this skill for direct TIA Portal interaction through the MCP server. The server exposes exactly ten public MCP tools: three batch tools and seven project lifecycle tools. Internal worker operations, including lifecycle probes, are not MCP-visible tools.

Use MCP for exploration, inspection, and bounded changes. For loops, bulk automation, or an operation outside this surface, use `tia-openness-roadmap`.

Public tool surface

Data operations

| Tool | Purpose | |---|---| | `execute_read_batch` | Run up to 50 independent read operations. | | `preview_write_batch` | Preview up to 50 data-write operations and obtain one batch safety token. | | `apply_write_batch` | Apply the exact previewed write batch sequentially; stop on the first failure and mark remaining items skipped. There is no transaction or rollback. |

Read-operation names include `browse_project_tree`, `get_block_content`, `list_tag_tables`, `read_hardware_config`, `read_cross_references`, `search_equipment_catalog`, `compile_check`, and `get_project_status`. Data-write operation names include block, tag-table, tag, user-constant, and network-device operations such as `update_block_logic`, `create_block`, `create_tag`, and `add_network_device`.

Project lifecycle

| Tool | Purpose | |---|---| | `get_project_status` | Inspect the currently open project. | | `open_project` | Deliberately open or switch to a project. | | `create_project` | Create a project. | | `save_project` | Save the open project. | | `save_project_as` | Copy the open project and rebind to the copy. | | `archive_project` | Create an archive of the open project. | | `close_project` | Close the open project. |

`get_project_status(projectPath)` is read-only and non-binding. It never opens or switches a project, including when `projectPath` names a different project. Use `open_project` for deliberate session switching. If a bound session names a different path in a status request, the result is `binding_conflict`; do not use status as a switching mechanism.

Safety convention

All writes use single-use, short-lived safety tokens bound to the normalized project path, exact input, target, and current project state. Never invent or reuse a token.

For data writes:

1. Send the full ordered `operations` array to `preview_write_batch`. 2. Review the preview and its `safetyToken`. 3. Send the unchanged array to `apply_write_batch` with `confirm:true` and that token.

For lifecycle writes, the tool previews itself: call the lifecycle tool without a `safetyToken` to receive a preview and token, then call the same tool with the same input, `confirm:true`, and the token to apply. Lifecycle writes remain single-tool only and cannot be placed in a data batch.

`save_project_as` requires `rebind:true`. Passing `rebind:false` is rejected as `validation_error` before preview, token issuance, Siemens `SaveAs`, or audit effects. After a successful SaveAs, continue with the worker-reported copied project path; do not assume a caller-supplied path is authoritative.

Never automatically retry a write after `worker_timeout`, `worker_crashed`, or protocol loss. The outcome may be uncertain: inspect current state before a new, separately authorized request.

Failures and warnings

Write failures return `failureCategory` with a human-readable error. Supported categories: `validation_error`, `binding_conflict`, `state_changed`, `worker_operation_failed`, `worker_timeout`, `worker_crashed`, and `postcondition_failed`.

`warnings` is a separate array of non-fatal degradation notes. A warning never turns a failure into a success, and a failure category is never hidden by warnings. Treat any warning as a signal that the returned payload can be partial.

Block write guidance

Read a block through `execute_read_batch` using `get_block_content`; use the returned SIMATIC ML documents as the source for a change. For `update_block_logic`, send a validated document bundle in a guarded data batch. The verified flow performs one import, compilation verification, and a non-empty re-export. Preserve unchanged documents exactly where possible; duplicate, malformed, or unsafe documents are rejected before any Siemens import, leaving the existing block unchanged.

For `create_block` with SCL, provide the requested block type and language in a guarded batch. The generated source has a non-empty Structured Text compile unit. After apply, resolve the requested block path and run `compile_check` to confirm it exists and compiles.

Common execution patterns

Inspect a block

1. Run `execute_read_batch` with `browse_project_tree` to find the block path. 2. Run `execute_read_batch` with `get_block_content` for that path. 3. Analyze the returned documents before deciding whether a write is needed.

Modify a block

1. Read the current documents with `execute_read_batch`. 2. Make one focused, validated document change. 3. Preview `update_block_logic` with `preview_write_batch`. 4. Confirm intent, then apply the unchanged batch with `apply_write_batch`, `confirm:true`, and the returned token. 5. Review compilation and re-export verification. On an uncertain outcome, read current state instead of retrying automatically.

Switch projects safely

1. Inspect the open project with `get_project_status` if needed. 2. Preview `open_project` by calling it without a `safetyToken`. 3. Apply the same request with `confirm:true` and its token. 4. Verify the worker-reported path with `get_project_status`.

Add and configure a device

1. Read the hardware catalog through `execute_read_batch` and copy the exact `typeIdentifier`. 2. Preview ordered add/configure operations in one `preview_write_batch` request. 3. Confirm the identity and networ