TIA Portal V20 Unified MCP / 博途 V20 统一 MCP

English | 中文

An MCP server for Siemens TIA Portal V20 Openness, tuned for single-engineer PLC/HVAC field commissioning, high-precision temperature/humidity projects, and AI-agent assisted project work.

面向 Siemens TIA Portal V20 Openness 的 MCP 服务端，针对单人工程师负责整套 PLC/暖通项目、高精密恒温恒湿实验室现场调试，以及 AI Agent 辅助项目操作的工作方式做了优化。

Core route / 核心路线：

inspect project -> export XML snapshot -> let the LLM reason over complete engineering context -> preview changes -> import through Openness -> compile -> save or roll back

检查工程 -> 导出 XML 快照 -> 由 LLM 基于完整工程上下文判断 -> 预演改动 -> 通过 Openness 导入 -> 编译 -> 保存或回滚

Project Positioning / 项目定位

English	中文
Target platform: TIA Portal V20 with the classic V20 Openness DLL layout.	目标平台：TIA Portal V20，使用 V20 版本未大拆分前的 Openness DLL 结构。
Workflow target: one engineer owns and debugs the whole local project.	工作流目标：一个工程师负责并调试整个本地项目。
Project type: local .ap20 projects. Multiuser/local-session .alsXX workflows were removed.	项目类型：本地 .ap20 项目。已移除 Multiuser/local session .alsXX 工作流。
MCP transport: stdio, suitable for Copilot, Claude Desktop, Codex, and other local MCP clients.	MCP 通信：stdio，适合 Copilot、Claude Desktop、Codex 等本地 MCP 客户端。
Packaging: a standalone .NET Framework 4.8 MCP server.	打包方式：独立的 .NET Framework 4.8 MCP 服务端。

Important V21 Notice / 关于 Portal V21 的重要说明

English	中文
This repository is intentionally focused on TIA Portal V20.	本仓库明确以 TIA Portal V20 为主目标。
TIA Portal V21 changed the Openness/Public API DLL layout significantly. In practical terms, the V21 DLL dependency structure is very different and has been split into many DLLs.	TIA Portal V21 对 Openness/Public API DLL 布局做了明显大改。实际使用中，V21 的 DLL 依赖结构与 V20 差异很大，并拆分成更多 DLL。
This project targets the V20 layout, before the V21-style DLL split.	本项目针对的是 V20 DLL 结构，也就是 V21 大拆分之前的版本。
If your goal is AI-agent based TIA Portal or project automation, upgrading a working V20 automation environment to V21 is not recommended right now.	如果你的目标是让 AI Agent 参与博途或项目自动化，目前不建议把已经能工作的 V20 自动化环境升级到 V21。
V21 support in this project is limited and not the recommended path.	本项目对 V21 的支持很少，也不是推荐路线。
Use V21 only if you are ready to redo and validate the Siemens Openness resolver, assembly loading, test assets, and tool behavior against the new DLL layout.	只有在你准备好针对新的 DLL 布局重新验证 Siemens Openness 解析、程序集加载、测试资产和工具行为时，才建议考虑 V21。

What This Is Good For / 适合什么场景

English	中文
Field commissioning where one engineer opens, inspects, exports, imports, compiles, and saves one local TIA project.	现场调试时，一个工程师打开、检查、导出、导入、编译、保存一个本地博途项目。
HVAC and high-precision temperature/humidity work: trace sensors, scaling, correction values, setpoints, PID parameters, alarms, and actuator outputs.	暖通与高精密恒温恒湿项目：追踪传感器、量程、修正值、设定值、PID 参数、报警和执行器输出。
AI-agent assisted navigation of project structure, PLC software, blocks, and PLC data types.	让 AI Agent 辅助浏览项目结构、PLC 软件、程序块和 PLC 数据类型。
Read-heavy workflows with explicit write tools for import/export/save operations.	以读取和检查为主，同时提供明确的导入、导出、保存等写操作。
Batch export/import workflows where partial success and per-item issues must be visible.	批量导入/导出时，需要看到部分成功和每个对象失败原因的场景。
Explicit MCP configuration where the client starts the server process directly.	使用显式 MCP 配置，由客户端直接启动服务端进程。

What This Is Not / 不适合什么场景

English	中文
It is not a Multiuser engineering workflow.	这不是 Multiuser 多人协作工程流。
It does not target .alsXX local sessions.	不针对 .alsXX 本地 session。
It is not a V21-first compatibility layer.	不是以 V21 为优先目标的兼容层。
It does not replace engineering judgment before downloads, hardware changes, or safety-related work.	不能替代下载、硬件改动、安全相关操作前的工程判断。

Tool List / 工具清单

Portal And Project / Portal 与项目

Tool	English	中文
Connect	Attach to a running TIA Portal instance or start one.	连接已有博途实例，或启动一个新的博途实例。
Disconnect	Dispose the Openness connection.	释放 Openness 连接。
GetState	Return connection and active project state.	返回连接状态和当前项目状态。
GetProject	List open local projects.	列出当前打开的本地项目。
OpenProject	Open a local .apXX project; reuses the already-open project when possible.	打开本地 .apXX 项目；如果同名项目已打开会优先复用。
SaveProject	Save the active local project.	保存当前本地项目。
SaveAsProject	Save the active local project to a new directory.	将当前本地项目另存到新目录。
CloseProject	Close the active local project and clear server project state.	关闭当前本地项目并清理服务端项目状态。

Connect uses Siemens' standard TiaPortalProcess.Attach() flow. When TIA shows the Openness access dialog, the client should keep the same request and server process alive until the engineer approves it. The server does not automatically restart or terminate TIA Portal while authorization is pending.

Connect 使用 Siemens 标准的 TiaPortalProcess.Attach() 流程。TIA 弹出 Openness 访问授权框后，客户端应保持同一请求和同一服务端进程等待工程师确认；授权等待期间，服务端不会自动重启或结束博途。

Project Structure / 项目结构

Tool	English	中文
GetProjectTree	Return a tree view of devices, groups, and software containers.	返回设备、分组和软件容器的项目树。
GetDevices	List devices in the active project.	列出当前项目中的设备。
GetDeviceInfo	Inspect one device by project path.	按项目路径查看单个设备信息。
GetDeviceItemInfo	Inspect one device item by project path.	按项目路径查看单个设备项信息。

PLC Software / PLC 软件

Tool	English	中文
GetSoftwareInfo	Inspect one PLC software object by softwarePath.	按 softwarePath 查看 PLC 软件对象信息。
GetSoftwareTree	Return the PLC block/type hierarchy for a software object.	返回指定 PLC 软件下的程序块/类型层级树。
CompileSoftware	Compile PLC software, with optional safety password support.	编译 PLC 软件，可选安全程序密码。

Blocks / 程序块

Tool	English	中文
GetBlockInfo	Inspect one block by full block path.	按完整 block 路径查看单个程序块。
GetBlocks	List blocks by name or regex.	按名称或正则列出程序块。
GetBlocksWithHierarchy	Return a structured block hierarchy.	返回结构化程序块层级。
ExportBlock	Export one block to XML.	导出单个程序块为 XML。
ImportBlock	Import one XML block with override behavior.	导入单个 XML 程序块，使用覆盖逻辑。
ExportBlocks	Batch export blocks to XML and return items, inconsistent blocks, issues, and metadata.	批量导出程序块为 XML，并返回成功项、不一致项、问题和元数据。
GenerateBlocksFromSource	Generate PLC blocks from an external .scl source file through TIA Openness external sources; normalizes source encoding for Chinese comments.	通过 TIA Openness 外部源，从 .scl 源文件生成 PLC 程序块；会规范化源码编码以支持中文注释。

Project Analysis / 项目分析

Read-only tools follow the Siemens Openness XML route: export a timestamped XML snapshot first, then parse the snapshot. Patch tools use the same route, but add backup XML, patched XML, ImportBlock, optional compile, optional save, and rollback controls.

只读工具遵循 Siemens Openness XML 路线：先导出带时间戳的 XML 快照，再解析快照。写入工具使用同一路线，但会增加备份 XML、补丁 XML、ImportBlock、可选编译、可选保存和回滚控制。

Analog patch requests are validated atomically before XML changes. Invalid numeric values, unsupported fields, ambiguous selectors, or missing writable access nodes return structured issues without partially patching the working XML. Integer inputs for TIA REAL constants are normalized to literals such as 50.0.

模拟量补丁会在修改 XML 前进行整条请求的原子校验。非法数值、不支持字段、多匹配选择器或缺失可写节点时，会返回结构化问题，不会部分修改工作 XML。写入 TIA REAL 常量时，整数输入会规范化为 50.0 这类合法字面量。

Read-only analysis snapshots are reused for up to 30 seconds inside one MCP/TIA session. A full-project snapshot can serve later DB, tag-usage, analog, and preview queries. Set forceRefresh=true when a fresh export is required. Project switching, imports, source generation, document imports, compile, and Save As invalidate the cache automatically.

同一 MCP/TIA 会话内，只读分析快照最多复用 30 秒。完整工程快照可继续用于 DB、点位引用、模拟量和预演查询。需要实时重新导出时设置 forceRefresh=true。切换工程、导入、外部源生成、文档导入、编译和另存会自动清空缓存。

The analysis layer deliberately returns original engineering structure instead of hard-coding narrow HVAC semantics. The LLM receives DB members, symbols, block/network context, call wiring, and exact references, then performs the project-specific reasoning.

分析层刻意保留原始工程结构，不把暖通业务语义硬编码成细碎字段。MCP 向 LLM 提供 DB 成员、符号、块/程序段上下文、调用接线关系和准确引用，再由 LLM 结合当前项目完成判断。

Tool	English	中文
AnalyzeDbMembers	Export blocks and return complete DB member definitions, including datatype, retain/remanence, and nested names.	导出程序块并返回完整 DB 成员定义，包括数据类型、保持属性和嵌套名称。
AnalyzeParameterDbs	Return parameter DB members and their exact tag usages without inferring business semantics.	返回参数 DB 成员及其准确引用位置，不预先推断业务语义。
FindTagUsages	Find tag usages across exported block networks, including block name and network title.	在导出的程序块网络中查找点位引用，返回块名和程序段标题。
AnalyzeAnalogInputs	Parse Convert_IW calls in analog input blocks and return raw input, scaling, correction, and engineering output.	解析模拟量输入块中的 Convert_IW 调用，返回原始输入、量程、修正值和工程量输出。
AnalyzeAnalogOutputs	Parse Convert_QW calls in analog output blocks and return engineering input, scaling, and raw output.	解析模拟量输出块中的 Convert_QW 调用，返回工程量输入、量程和原始输出。
PreviewAnalogInputPatches	Dry-run analog input scaling/correction changes and return before/after without modifying XML or TIA.	预演模拟量输入量程/修正值变更，返回 before/after，不修改 XML 或 TIA。
PreviewAnalogOutputPatches	Dry-run analog output scaling changes and return before/after without modifying XML or TIA.	预演模拟量输出量程变更，返回 before/after，不修改 XML 或 TIA。
ApplyAnalogInputPatches	Apply Convert_IW changes through export backup -> patch XML -> import -> compile/save/rollback.	通过导出备份、补丁 XML、导入、编译/保存/回滚流程应用 Convert_IW 变更。
ApplyAnalogOutputPatches	Apply Convert_QW changes through export backup -> patch XML -> import -> compile/save/rollback.	通过导出备份、补丁 XML、导入、编译/保存/回滚流程应用 Convert_QW 变更。

PLC Data Types / PLC 数据类型

Tool	English	中文
GetTypeInfo	Inspect one PLC data type.	查看单个 PLC 数据类型。
GetTypes	List PLC data types by name or regex.	按名称或正则列出 PLC 数据类型。
ExportType	Export one PLC data type to XML.	导出单个 PLC 数据类型为 XML。
ImportType	Import one XML PLC data type.	导入单个 XML PLC 数据类型。
ExportTypes	Batch export PLC data types and return structured issue details.	批量导出 PLC 数据类型，并返回结构化问题详情。

V20 SIMATIC SD Documents / V20 SIMATIC SD 文档

Use GenerateBlocksFromSource for newly written SCL source. The tools below are for SIMATIC SD documents exported by TIA Portal, not hand-written .scl.

新写 SCL 源码请使用 GenerateBlocksFromSource。下面这些工具用于 TIA Portal 导出的 SIMATIC SD 文档，不用于手写 .scl 源文件。

GenerateBlocksFromSource passes TIA Portal a UTF-8 BOM temporary source file, which avoids false syntax errors when .scl contains Chinese comments.

GenerateBlocksFromSource 会向 TIA Portal 传入 UTF-8 BOM 临时源文件，避免 .scl 含中文注释时被误判为语法错误。

Tool	English	中文
ExportAsDocuments	Export one supported block as .s7dcl/.s7res.	将单个受支持的程序块导出为 .s7dcl/.s7res。
ExportBlocksAsDocuments	Batch export supported blocks as .s7dcl/.s7res, preserving per-block issues.	批量导出受支持的程序块为 .s7dcl/.s7res，保留每个块的问题详情。
ImportFromDocuments	Import one .s7dcl/.s7res document pair.	导入一组 .s7dcl/.s7res 文档。
ImportBlocksFromDocuments	Batch import document blocks from .s7dcl files with warning and issue reporting.	按 .s7dcl 批量导入文档块，并报告警告和问题。

Recommended Agent Workflow / 推荐 Agent 工作流

1. Connect / 连接博途。
2. OpenProject / 打开本地 .ap20 项目。
3. GetProjectTree / 读取项目树，找到设备和 softwarePath。
4. GetSoftwareTree / 读取 PLC 软件树，找到 block/type 路径。
5. Use AnalyzeDbMembers, AnalyzeParameterDbs, AnalyzeAnalogInputs, AnalyzeAnalogOutputs, and FindTagUsages to build a structured snapshot / 使用这些分析工具建立结构化快照。
6. Use PreviewAnalogInputPatches or PreviewAnalogOutputPatches for dry-run before any import/write action / 任何导入或写入前先使用 preview 工具预演。
7. Check snapshotPath, snapshotReused, Issues, Meta.partial, and before/after values; use forceRefresh=true after manual TIA edits / 检查快照路径、复用标记、问题列表、部分成功标记和 before/after；在 TIA 中手工修改后使用 forceRefresh=true。
8. For analog batches, use ApplyAnalogInputPatches or ApplyAnalogOutputPatches only after the preview is unambiguous; keep apply=false until the write is intentional / 批量模拟量修改必须先预演明确，再用 apply 工具；不准备写入时保持 apply=false。
9. Keep rollbackOnFailure=true; use rollbackAfterCompile=true for field-path validation without leaving edits behind / 保持失败回滚；现场验证链路但不保留改动时使用 rollbackAfterCompile=true。
10. SaveProject only when changes should persist / 只有需要保留改动时才保存项目。
11. CloseProject and Disconnect when finished / 完成后关闭项目并断开连接。

Field Engineer Example / 现场工程师示例

For one room or one AHU, a practical agent session normally keeps one Portal connection and performs several related checks together:

针对一个房间或一台空调机组，实际 Agent 会话通常保持同一个 Portal 连接，并一次完成一组关联检查：

1. Locate the temperature/RH raw inputs, engineering outputs, ranges, and correction values / 找到温湿度原始输入、工程量输出、量程和修正值。
2. Trace the values into control logic, PID parameters, upper/lower alarms, HMI data, and actuator outputs / 追踪到控制逻辑、PID 参数、上下限报警、HMI 数据和执行器输出。
3. Preview a batch correction or range change and reject no-match or ambiguous selectors / 预演批量修正值或量程修改，拒绝未匹配和多匹配选择器。
4. Save As a field-test copy, import once, compile once, and either keep the verified result or roll it back / 另存现场测试副本，一次导入、一次编译，验证后保留或回滚。

The server should not close and reopen TIA Portal between these steps. Snapshot reuse and transaction-style patch tools are designed to reduce repeated exports, repeated attaches, and unnecessary Portal resource use.

这些步骤之间不应反复关闭和重开博途。快照复用和事务式补丁工具用于减少重复导出、重复附加和不必要的 Portal 资源消耗。

Requirements / 环境要求

English	中文
Windows machine.	Windows 机器。
Siemens TIA Portal V20 installed.	已安装 Siemens TIA Portal V20。
.NET Framework 4.8 developer/runtime support.	.NET Framework 4.8 开发/运行环境。
Environment variable TiaPortalLocation=C:\Program Files\Siemens\Automation\Portal V20.	环境变量 TiaPortalLocation=C:\Program Files\Siemens\Automation\Portal V20。
Current Windows user in Siemens TIA Openness.	当前 Windows 用户属于 Siemens TIA Openness 用户组。

Build / 构建

dotnet restore .\server\TiaMcpServer.csproj
dotnet build .\server\TiaMcpServer.csproj -c Release

Expected executable / 生成的可执行文件：

server\bin\Release\net48\TiaV20UnifiedMcpServer.exe

Run the offline readiness check / 运行离线就绪检查：

.\scripts\Test-OfflineReadiness.ps1 -BuildServer

MCP Client Configuration / MCP 客户端配置

Example server entry for an MCP stdio client / MCP stdio 客户端服务配置示例：

{
  "name": "tia-v20-unified-mcp",
  "command": "C:\\path\\to\\TiaV20UnifiedMcpServer.exe",
  "args": [
    "--tia-major-version",
    "20",
    "--logging",
    "stderr",
    "--transport",
    "stdio"
  ],
  "env": {}
}

Verification / 验证

Validated on a TIA Portal V20 machine with the provided local test project:

已在 TIA Portal V20 环境和本地测试项目上验证：

The internal handoff package should not include Siemens/TIA Portal paid software, Openness DLLs, generated build output, or local TIA project archives such as TestProject1.zap20.

内部交付包不应包含 Siemens/TIA Portal 付费软件、Openness DLL、生成的构建产物，也不应包含 TestProject1.zap20 这类本地 TIA 项目归档。

Offline XML transaction tests:

dotnet test .\tests\TiaMcpServer.Unit\TiaMcpServer.Unit.csproj -c Release

Latest V20 field validation used a SaveAsProject copy of a real HVAC project:

• 66 Convert_IW input channels and 26 Convert_QW output channels analyzed.
• Exact, ambiguous, and invalid patch guards verified.
• Input patch import, compile, rollback import, and rollback compile succeeded.
• Output patch import, compile, rollback import, and rollback compile succeeded.
• Two input channels were patched in one XML import and one compile transaction, then restored.
• The original .ap20 SHA-256 remained unchanged.

最新 V20 现场验证使用真实暖通项目的 SaveAsProject 副本：

• 分析 66 个 Convert_IW 输入通道和 26 个 Convert_QW 输出通道。
• 已验证精确匹配、多匹配阻止和非法值阻止。
• 输入补丁导入、编译、回滚导入、回滚编译全部成功。
• 输出补丁导入、编译、回滚导入、回滚编译全部成功。
• 两个输入通道在一次 XML 导入和一次编译事务中完成修改并恢复。
• 原始 .ap20 的 SHA-256 保持不变。

dotnet test .\tests\TiaMcpServer.Test\TiaMcpServer.Test.csproj -c Release --no-build

Latest local result after removing Multiuser/session coverage:

移除 Multiuser/session 覆盖后的本地结果：

77 passed, 0 failed, 0 skipped
77 通过，0 失败，0 跳过

Repository Layout / 仓库结构

Path	English	中文
server/	.NET Framework 4.8 MCP server and Siemens Openness wrapper.	.NET Framework 4.8 MCP 服务端和 Siemens Openness 封装层。
tests/	MSTest integration tests for V20 local project workflows.	针对 V20 本地项目工作流的 MSTest 集成测试。
docs/	Architecture notes, tool matrix, and verification notes.	架构说明、工具矩阵和验证说明。
scripts/	Local readiness checks.	本地环境就绪检查脚本。

Internal Handoff Boundary / 内部分发边界

English	中文
Share source code, docs, scripts, package manifests, and non-proprietary assets only.	只分发源码、文档、脚本、包清单和非专有素材。
Do not include Siemens/TIA Portal paid software, installer files, Openness DLLs, or generated server binaries unless your company license and delivery process explicitly allow it.	不要包含 Siemens/TIA Portal 付费软件、安装包、Openness DLL 或生成的服务端二进制，除非公司授权和交付流程明确允许。
Do not include real project archives or exports, including .apXX, .zapXX, .alsXX, .s7p, .s7dcl, and .s7res.	不要包含真实项目归档或导出文件，包括 .apXX、.zapXX、.alsXX、.s7p、.s7dcl、.s7res。
Do not include private authentication files, certificates, keys, .env files, local MCP configuration, or machine-specific credentials.	不要包含私有鉴权文件、证书、密钥、.env、本地 MCP 配置或机器专用凭据。
Integration-test assets are local-only and must be recreated by each developer on their own machine.	集成测试资产只保留在本地，每个开发者需要在自己的机器上准备。

License / 许可证

This repository keeps the upstream MIT license notice in LICENSE.upstream-heilingbrunner.txt.

本仓库保留上游 MIT 许可证声明，见 LICENSE.upstream-heilingbrunner.txt。