TIA Codex Bridge

An MCP bridge for Siemens TIA Portal Openness that lets Codex and other AI assistants inspect PLC projects, import or export programs, and compile with read-only defaults and opt-in writes.

通过 MCP → Python.NET → Siemens TIA Portal Openness，让本机 Codex 读取、导入、编译和保存 TIA 工程。使用本地标准输入输出（stdio），桥本身不调用任何 AI API，也不开网络监听端口。

版本 0.1.0 是需要 Windows/TIA 实机验收的初始实现。 开发环境没有 TIA Portal；协议、文件保护、适配层替身测试不代表真实 Siemens 接口已经运行成功。默认对齐 V20 官方文档，V19 可配置但未验证。没有实际测试过的 TIA 版本不会标成“已兼容”。

能做什么

默认禁止导入、编译和保存；启动时加 --allow-writes 开启。编译也可能改变离线工程数据，因此按修改操作处理。导出只创建新的本地文件。

本版不提供 PLC 下载、CPU RUN/STOP、强制 I/O、在线变量写入、硬件组态修改、HMI 编辑或任意脚本执行接口。不接管已经打开的 TIA 实例，不自动处理 UMAC/保护密码，不自动放行 Openness 访问提示。

Related MCP server: tiacommander-mcp

Windows 安装

需要：

1. 安装 TIA Portal STEP 7 与匹配版本的 Openness，具备相应许可证和项目所需的选件/HSP。

2. 当前 Windows 用户加入 Siemens TIA Openness 本地组，重新登录使组成员资格生效。可在“计算机管理 → 本地用户和组”中设置。

3. Python 3.11 x64（也接受 3.12，Linux 核心层已测；Windows interop 待验收）、.NET Framework 4.8、本机 Codex。

4. 遇到 Siemens 的 Openness 授权提示时，由用户在本机处理。不要关闭安全提示来绕过授权。

将仓库下载到例如 C:\Dev\tia-codex-bridge，在该目录的 PowerShell 中运行：

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[windows]"

安装仅依赖 Python.NET 调用 CLR。Siemens DLL 使用 TIA 本机安装目录中的文件，仓库不附带也不重新分发原厂 DLL。

准备两个独立、不互相嵌套的目录：

C:\TIA\Projects\Demo\Demo.ap20
C:\TIA\BridgeWork

Demo 必须是完整、已保存并关闭的工程文件夹，包含伴随文件。不能仅复制 .ap20 单个文件，不能把所有项目混放在同一工程文件夹。桥会复制其整个父文件夹，复制前后检查源目录是否变化；这不是对正在编辑工程的事务快照。当前复制上限为 2 GiB / 20,000 个文件及目录，超限直接拒绝。

项目根目录和工作目录使用本地固定磁盘；拒绝 UNC、映射网络盘、符号链接和 Windows junction/reparse point。两个目录都应放在 Git 工作区之外。

连接 Codex

将 config/codex.example.toml 中的表合并到本机 %USERPROFILE%\.codex\config.toml，修改 Python、工程根目录、工作目录和 TIA PublicAPI 路径。不要覆盖已有 Codex 配置，也不要上传真实配置。

然后重启 Codex，检查 MCP 工具列表。默认使用真实 Openness 后端；仅 open_project 第一次执行时加载原厂 DLL 和启动 TIA，因此 MCP 握手不会被 TIA 启动拖住。

这是 Windows 本机 的桥。当前云端聊天、手机和纯 Linux/WSL Python 不能直接访问你电脑里的 Openness。此配置使用原生 Windows Python，由运行在同一 Windows 主机上的 Codex 启动。桥不需要 OpenAI API Key；Codex 自身的登录/模型权限照常由 Codex 管理。

一次完整操作

先对 Codex 说：

使用 tia_openness，先查 status，确认 simulated=false。打开 Demo/Demo.ap20 的工作副本，列出 PLC 和程序块，先不要修改。

open_project 返回 sessions/<本次标识>/Demo.ap20。这个路径相对于工作目录，是之后保存的目标。原工程一直留在项目根目录中。

要试验 SCL：将 examples/BridgeDemo.scl 放到 C:\TIA\BridgeWork\staging\BridgeDemo.scl；在 Codex MCP 配置的 args 中加上 --allow-writes，重启桥，再打开一次新副本。

在确认的 PLC 中，读取 staging/BridgeDemo.scl，检查代码并记录返回的 sha256；用这个值作为 expected_sha256 导入，allow_replace=true；然后编译，解释所有错误和警告，确认结果后保存工作副本。

工具调用的 plc_id 和 block_id 必须取自当前会话的列表，不能猜。expected_sha256 必须来自实际待导入文件；读取后文件变化会导致导入被拒绝。导入会再生成固定内容的新文件，确保传给 Openness 的是检查过的字节。

SCL 生成可能覆盖同名块/类型，因此必须传 allow_replace=true。它不是“绝不覆盖”的新增接口。失败也可能留下部分修改，检查工作副本后决定继续修复或重新从原工程开始。源文件会保留在 TIA 的 External sources 中，不自动删除。

编译结果的 errors 大于零时，应先修正。本版没有完整 SCL 解析器、梯形图语义验证器或真实设备仿真器；编译是否通过必须以本机 TIA 结果为准。示例只有布尔逻辑，没有映射物理 I/O。

梯形图怎么处理

Openness 通过 SimaticML XML 表达 LAD/FBD 等程序块。先 export_block，再 read_artifact，让 Codex 根据真实导出结构修改副本 XML，放入 staging/，最后导入并编译。

不会直接把任意自然语言自动转换为已验证的梯形图。 本版未实现鼠标画图、自动布局或 SCL→LAD 转换。XML 导入只面向普通程序块并导入根块组；若原块在子组，需在 TIA 检查目标分组及引用，不保证原有分组位置不变。Software Units、Safety Units、库类型、特殊保护块不在已实现范围内。

SCL 入口按所查 Openness 文档保守限定为 ASCII；中文注释/标识符请先换成 ASCII，或使用相应版本的合法 UTF-8 SimaticML XML。不会静默改写编码。

超时、保存与关闭

Openness 调用在同一个 STA 线程上串行执行。默认操作超时 240 秒，示例 Codex 工具超时为 300 秒；可把 --operation-timeout 调整到 10–600 秒，并让 Codex 超时更长。

超时后操作可能仍在 TIA 内完成，桥将拒绝后续 Openness 操作，status 会显示 session_uncertain=true。不要自动重试导入/保存；先检查 TIA UI 的副本状态，再重启桥。不会声称已回滚，也不会强杀 TIA。

桥退出不自动保存，也不主动关闭 TIA 中打开的项目。因为使用带界面的实例，UI 可保留供你检查或恢复未保存修改。一个桥进程只打开一个工程；需要另一个工程时，先处理当前修改，再重启桥。新的 open 总是创建新的工作副本，不会自动接着之前的副本改。

发布前检查

仓库公开意味着代码可以被浏览和复制；敏感信息检查的作用是阻止凭据及内部配置随代码发布，不是阻止爬虫访问公开代码。

上传前先审查 git status 和 git diff --cached，仅暂存准备发布的源码，然后运行：

python scripts/scan_publish.py --staged --history

只有退出码为 0 才继续推送。检查的是 Git 暂存区实际内容与所有本地可达历史，包括历史里已经删除的文本。扫描失败或无法完成时返回非零；输出只含位置/规则，不打印匹配值。支持 --report 将包含文件 SHA-256 清单的报告存到仓库外。

启用本地提交/推送检查：

git config core.hooksPath .githooks

Git 钩子需要本机 python3 或 python 命令可用。预提交检查暂存区，预推送再检查历史。任何人都能禁用自己机器的 Git 钩子；这不是不可绕过的访问控制。GitHub Actions 中的扫描发生在上传之后，只提供补充检查，不能代替上传前扫描。

检查规则、剩余风险及 Windows 验收步骤见 SECURITY.md 与 docs/windows-acceptance.md。

开发与测试

核心协议层不依赖外部包，可以在 Linux/Windows 运行：

python -m unittest discover -s tests -v
python -m compileall -q tia_bridge scripts

--backend mock 仅用于无 TIA 环境的协议开发：工具结果始终标注 simulated=true，模拟“编译”返回 MOCK_NOT_COMPILED 和空错误计数，不伪造“零错误编译成功”。Mock 使用临时测试工程文件，与真实 .ap20 内容无关。

GitHub 的 Linux/Windows CI 测协议和文件检查；托管 runner 未安装 TIA，不构成实机验收。已做及未做的验证见 docs/verification.md。

接口依据仅使用原厂/项目官方资料，链接集中在 docs/sources.md。