tia-portal-openness-mcp

TIA Portal MCP 完整交付包（v2.2.8 / V20+V21 + S7DCL + CLI + 在线只读监控 + 一键配置 + Doctor 体检）

English · 中文

免费开源（MIT）：服务器无需任何 license key 即可运行，不含任何授权校验代码。

在 Windows + TIA Portal V20 或 V21 下，通过 MCP（stdio 或 HTTP） 驱动博途：建项目、加硬件、生成 PLC（Tag/UDT/DB/SCL/LAD）、生成 WinCC Unified 画面与事件、编译诊断、保存。
包内含 已编译运行时、Skill、静态工具清单、能力矩阵、PLC/HMI 模板、一键可读的项目蓝图与手册。不要求另行克隆源码仓库。

⚡ 最快上手（3 步，零编程·CLI 路线）

第一次用？不需要 MCP 客户端、不需要写代码。 装好 TIA 后照这 3 步，几分钟内生成第一个工程。 （想接 Cursor / Claude Desktop 等 AI 客户端走 MCP？跳到下方 上手步骤。）

1. 准备：装好 TIA Portal V20 或 V21 + .NET Framework 4.8；把当前 Windows 用户加入本地组 Siemens TIA Openness，注销重登一次。装的是哪个版本就用哪个——交付包根目录已备好 tia.cmd（V21）/ tia-v20.cmd（V20），其余路径自动选。
2. 预热（可选但强烈推荐）：双击 scripts\预热.bat，留着这个窗口。它常驻一个无界面 TIA，让之后每条命令 ~1 秒连上（不预热则每次冷启动约 3 分钟）。用完按 Ctrl+C 关闭。
3. 生成工程：把现成模板 templates\project-blueprints\scaffold_spec_motor.json（或 scaffold_spec_start_stop.json）拖到 scripts\生成工程.bat 图标上——一条龙建项目→加 PLC/HMI→写块→编译→存盘。退出码 0 即成功。
   • 想改成自己的需求：让任意 AI 照 docs/AI_spec_prompt.md 产出一份 spec（YAML/JSON 都行），再拖给 生成工程.bat。
   • 命令行等价写法：把根目录加进 PATH 后，tia gen <spec>（先 --dry-run 离线校验更稳）。

v2.0.0 新功能 —— tia 命令行（门槛最低、任意 AI 可用）

同一个 exe 既是 MCP 服务，也是命令行。 任意 AI 产出一份 YAML/JSON spec，任意工程师跑一条命令即可从零建/改工程——不需要 MCP 客户端、不需要安装。底层完全复用现有引擎。详见 docs/CLI_quickstart.md。

• tia gen <spec.yaml|json>：一条命令从 spec 建完整工程（= ScaffoldProject）。--dry-run 离线校验、--json 机器可读。
• tia patch <spec>：把 spec 增量 upsert 进已有工程（spec 内 projectPath 指向 .apXX），未提及的元素不动；--no-overwrite 保护手改的 LAD 代码块。
• 还有 tia compile / describe / export / import / prewarm / schema / version。退出码 0=成功 / 1=有失败步骤 / 2=错误。
• tia 命令入口：交付包根目录的 tia.cmd（V21）/ tia-v20.cmd（V20）——把根目录加进 PATH 即可随处 tia gen ...，不必记忆深层 exe 路径。
• 零编程上手：把 spec 拖到 scripts\生成工程.bat 上即可（V21 缺失自动回退 V20）；scripts\预热.bat 常驻 headless 实例让后续命令 ~1s 连上。
• 现成模板开箱即用：templates/project-blueprints/ 的启停/电机 spec 直接 tia gen 即可，tia 自动解析其中 __BUNDLE__ 为交付包根目录，无需手改路径。
• 让任意 AI 生成 spec：见 docs/AI_spec_prompt.md —— 通用契约「产出一份 spec」，不要求 AI 支持 MCP。
• YAML + JSON 双解析：JSON 首选（零歧义），YAML 便于人读写；同一 spec 两者产出一致。

仍是双 V20/V21 binary、仍是完整 MCP 服务（tia verb 之外行为不变）。CLI 与 MCP 共享同一引擎。

v1.0.0 新功能（快、好用、不出错）

• 默认 headless 启动，连接快 ~10×：连 TIA 默认无界面（WithoutUserInterface），冷启动从约 200–340s 降到约 10–28s。要肉眼看博途时，启动 exe 加 --with-ui（或生成完直接打开 .ap21）。
• ScaffoldProject —— 一句话生成完整工程：传一个 JSON spec，一次调用完成「建项目 → 加 PLC/HMI 硬件 → UDT/DB/标签表 → SCL/LAD 块 → 编译 → HMI 连接/画面/变量 → 保存」，返回逐步报告。把约 20 步的 runbook 收成一次调用。dryRun=true 可离线校验 spec 再真跑。现成模板见 templates/project-blueprints/scaffold_spec_start_stop.json（启停）、scaffold_spec_motor.json（电机）。
• 常驻实例，会话秒连（可选）：开一个终端跑 python scripts/prewarm_tia.py 挂着，之后每个会话 Connect 约 0.8–1s。
• 更不易出错：HMI 软件路径自动探测（不再写死 HMI_RT_1）；连接对挂死/孤儿 TIA 实例加超时跳过；单块导入（ImportFromDocuments/ImportBlock）导入后回读确认并返回 Meta.verified。
• 工具收敛至 180（下线 4 个 Export*ToTemp 变体，并为易混的 Export/Import 工具补消歧描述）。

本次更新（相对 20260512 包）

• 稳定生成硬门槛（v0.0.39）：基于 v0.0.38，PlcBuildAndImport 会返回 CapabilityDecision / CapabilityWarnings / RecommendedNextActions；ApplyUnifiedHmiScreenDesignJson(strict=true) 默认遇到 HMI 属性写入失败即报错；EnsureUnifiedHmiTag(requireVerifiedBinding=true) 默认要求读回 SymbolicVerified 或 AbsoluteVerified，避免“生成成功但变量未真实链接”的公开版体验问题。
• 双版本支持（V20 + V21）：包内含两个 exe — bin/Release/net48/TiaMcpServer.exe（V21 编译）与 bin-v20/Release/net48/TiaMcpServer.exe（V20 编译）。
  • 二者必须分别使用，不能互换：V21 用 split DLL（Siemens.Engineering.Base/Step7/...），V20 用单体 Siemens.Engineering.dll，IL 层面绑定不同。
  • 两份 exe 都接受新 CLI 参数 --tia-portal-location <path>，配合 --tia-major-version <20|21> 用于非标准安装位置。
• S7DCL/SCL 文本格式工具：ExportAsDocuments / ExportBlocksAsDocuments / ImportFromDocuments / ImportBlocksFromDocuments 在 V20+ 项目里以 SIMATIC SD 文本格式（.s7dcl + .s7res）导入导出程序块，比 SimaticML XML 更易读、diff 友好；描述里标注「PREFERRED on V21+」引导 AI 优先选用。
• V21 端到端验证（DemoProjects/MCP_Demo_Rich_20260523）：8 块导出 + 8 块导入回环 14.7s。
• V20 端到端验证（江夏测试5T车_V20）：CompileSoftware → ExportBlocksAsDocuments，51 个 .s7dcl + 33 个 .s7res 全量导出成功。LAD 块以 RUNG / I_Contact / Coil / TON{...} 文本表达，diff 友好。

与 IDE 无关：凡支持 MCP 的客户端（Cursor、VS Code、Claude Desktop、自研 HTTP 客户端等）均可使用同一 TiaMcpServer.exe。若某 IDE 中「看不到某个工具」，属于 客户端工具描述符/缓存 问题，不是交付包裁剪能力；见 docs/mcp-ide-and-tool-visibility.md。