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: Send the full ordered operations array to preview_write_batch . Review the preview and its safetyToken . 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 Run execute_read_batch with browse_project_tree to find the block path. Run execute_read_batch with get_block_content for that path. Analyze the returned documents before deciding whether a write is needed. Modify a block Read the current documents with execute_read_batch . Make one focused, validated document change. Preview update_block_logic with preview_write_batch . Confirm intent, then apply the unchanged batch with apply_write_batch , confirm:true , and the returned token. Review compilation and re-export verification. On an uncertain outcome, read current state instead of retrying automatically. Switch projects safely Inspect the open project with get_project_status if needed. Preview open_project by calling it without a safetyToken . Apply the same request with confirm:true and its token. Verify the worker-reported path with get_project_status . Add and configure a device Read the hardware catalog through execute_read_batch and copy the exact typeIdentifier . Preview ordered add/configure operations in one preview_write_batch request. Confirm the identity and network values, then apply the unchanged batch. Read hardware configuration and compile results to verify the change. Audit unused objects Run execute_read_batch with read_cross_references and filter="UnusedObjects" . Present the findings before proposing any deletion.