内容
# TIA-Portal MCP服务器
一款连接LLMs与西门子TIA Portal的MCP服务器，通过开放API实现。浏览项目、导出/导入模块、管理设备、下载到PLC等 — 所有操作均可通过AI助手完成。
## 快速入门
### 1. 前提条件
- Windows系统，且已安装**.NET Framework 4.8**
- 已安装并运行**西门子TIA Portal V20**
- 环境变量`TiaPortalLocation`设置为`C:\Program Files\Siemens\Automation\Portal V20`
- 用户属于Windows组**Siemens TIA Openness**
### 2. 下载
从[GitHub Releases](../../releases)下载`TiaMcpServer-<version>.zip`并解压。
### 3. 配置MCP客户端
**Claude Code** — 在工作空间的`.mcp.json`中添加：
```json
{
"servers": {
"tia-portal": {
"command": "C:\\path\\to\\TiaMcpServer.exe",
"args": [],
"env": {}
}
}
}
```
**Claude Desktop** — 在`%APPDATA%\Claude\claude_desktop_config.json`中添加：
```json
{
"mcpServers": {
"tia-portal": {
"command": "C:\\path\\to\\TiaMcpServer.exe",
"args": [],
"env": {}
}
}
}
```
**VS Code Copilot Chat** — 在`.vscode/mcp.json`中添加：
```json
{
"servers": {
"tia-portal": {
"command": "C:\\path\\to\\TiaMcpServer.exe",
"args": [],
"env": {}
}
}
}
```
> 对于TIA Portal V18或V19，添加`"--tia-major-version", "18"`到`args`中。
### 4. 使用
打开TIA Portal，然后要求AI助手连接并与项目交互。
## 从源代码构建
```bash
dotnet build -c Release
# 输出：src/TiaMcpServer/bin/Release/net48/TiaMcpServer.exe
```
## 可用工具（51）
### 连接与状态
| 工具 | 描述 |
|------|-------------|
| `Connect` | 连接到TIA Portal |
| `Disconnect` | 从TIA Portal断开连接 |
| `GetState` | 获取服务器状态（连接 + 项目） |
### 项目管理
| 工具 | 描述 |
|------|-------------|
| `GetProject` | 获取打开的项目/会话信息 |
| `OpenProject` | 打开一个项目/会话 |
| `CreateProject` | 创建一个新项目 |
| `SaveProject` | 保存当前项目 |
| `SaveAsProject` | 以新名称保存项目 |
| `ArchiveProject` | 将当前项目存档为压缩的.zap文件 |
| `RetrieveProject` | 从.zap存档中恢复项目 |
| `CloseProject` | 关闭当前项目 |
| `GetProjectTree` | 获取项目结构为树形视图 |
### 设备
| 工具 | 描述 |
|------|-------------|
| `GetDevices` | 列出所有设备 |
| `GetDeviceInfo` | 获取设备详细信息 |
| `GetDeviceItemInfo` | 获取设备项详细信息 |
| `AddDevice` | 从硬件目录添加设备 |
| `RemoveDevice` | 删除设备 |
| `SearchHardwareCatalog` | 搜索硬件目录 |
### PLC软件
| 工具 | 描述 |
|------|-------------|
| `GetSoftwareInfo` | 获取PLC软件信息 |
| `GetSoftwareTree` | 获取软件结构/树形 |
| `CompileSoftware` | 编译PLC软件 |
| `CompileHardware` | 编译硬件配置 |
### 模块（OB、FB、FC、DB）
| 工具 | 描述 |
|------|-------------|
| `GetBlocks` | 列出模块 |
| `GetBlockInfo` | 获取模块详细信息 |
| `GetBlocksWithHierarchy` | 列出模块及其分组层次 |
| `ExportBlock` | 导出单个模块 |
| `ExportBlocks` | 导出多个模块 |
| `ImportBlock` | 导入模块 |
| `ExportBlocksAsDocuments` | 以.s7dcl/.s7res格式导出模块（V20+） |
| `ImportBlocksFromDocuments` | 从.s7dcl/.s7res格式导入模块（V20+） |
| `ExportAsDocuments` | 以文档格式导出单个模块（V20+） |
| `ImportFromDocuments` | 从文档格式导入单个模块（V20+） |
### 类型（UDT）
| 工具 | 描述 |
|------|-------------|
| `GetTypes` | 列出类型 |
| `GetTypeInfo` | 获取类型详细信息 |
| `ExportType` | 导出类型 |
| `ExportTypes` | 导出多个类型 |
| `ImportType` | 导入类型 |
### PLC标签
| 工具 | 描述 |
|------|-------------|
| `GetPlcTagTables` | 列出PLC标签表 |
| `GetPlcTags` | 列出标签表中的标签 |
| `ExportPlcTagTable` | 导出标签表 |
| `ImportPlcTagTable` | 导入标签表 |
### HMI屏幕
| 工具 | 描述 |
|------|-------------|
| `GetHmiScreens` | 列出HMI屏幕 |
| `ExportHmiScreen` | 导出HMI屏幕 |
| `ImportHmiScreen` | 导入HMI屏幕 |
### 库
| 工具 | 描述 |
|------|-------------|
| `GetLibraries` | 列出可用库 |
| `GetLibraryMasterCopies` | 列出主副本 |
| `CopyFromLibrary` | 将主副本复制到PLC |
### 网络
| 工具 | 描述 |
|------|-------------|
| `GetNetworkInterfaces` | 获取设备网络接口 |
| `GetSubnets` | 列出项目子网 |
| `CreateSubnet` | 创建子网 |
| `ConnectToSubnet` | 将设备连接到子网 |
| `SetNetworkAttribute` | 设置网络属性（例如IP） |
### 在线与下载
| 工具 | 描述 |
|------|-------------|
| `DownloadToDevice` | 将软件下载到PLC |
| `GoOnline` | 与设备在线连接 |
| `GoOffline` | 离线连接 |
### 安全（F-CPU）
| 工具 | 描述 |
|------|-------------|
| `GetSafetyInfo` | 获取安全信息 |
| `CompileSafety` | 编译安全程序 |
## TIA Portal版本
- **V20** 是默认版本。
- 早期版本（V18，V19）通过`--tia-major-version`参数支持。
- 以文档格式导出/导入（.s7dcl/.s7res）需要TIA Portal V20或更新版本。
## 已知限制
- 截至2025-09-02：从SIMATIC SD文档导入梯形图（LAD）模块需要配套的`.s7res`文件包含所有项目的en-US标签；否则导入可能会失败。这是TIA Portal Openness的一个已知限制/错误。
- `ExportBlock`需要完全限定的`blockPath`，例如`Group/Subgroup/Name`。如果仅提供名称，MCP服务器返回`InvalidParams`，并可能包含建议的可能完整路径。
## 测试
- 查看`tests/TiaMcpServer.Test/README.md`了解环境前提条件和测试资产设置。
- 标准命令：`dotnet test`（从仓库根目录运行）。
- 测试执行策略：提供运行测试，但仅在用户明确确认后执行。详细信息请参见`AGENTS.md`。
## 贡献
- 查看`agents.md`了解有关使用代理助手和测试执行策略（仅在用户明确确认后提供运行测试）的指南。
## 错误处理（ExportBlock）
- 门户层抛出`PortalException`，包含简短消息和`PortalErrorCode`（例如NotFound，ExportFailed），并在导出失败时将`softwarePath`、`blockPath`、`exportPath`附加到`Exception.Data`中，同时保留`InnerException`。
- MCP层将这些映射到`McpException`代码。对于`ExportFailed`，它包含来自底层错误的简洁原因；对于`NotFound`，它返回`InvalidParams`，并可能建议可能的完整块路径，如果提供了裸名称。
- 一致性要求：TIA Portal从不导出不一致的块/类型。单个导出返回`InvalidParams`，并附有消息，指示需要先编译。批量导出跳过不一致的项目，并将它们放在`Inconsistent`列表中与`Items`一起。
- 标准化：异常上下文元数据在门户方法的单个捕获中附加，然后在重新抛出之前，而不是在内联抛出站点。参见`docs/error-model.md`。
- 此标准化模式目前适用于`ExportBlock`，并将逐步扩展。
## 传输
- 当前支持：`stdio`
- 编程连接`AddMcpServer().WithStdioServerTransport()`。
- 对于stdio，日志必须发送到stderr以避免破坏JSON-RPC。
- 通过SDK可用：`stream`（自定义流）
- SDK公开`WithStreamServerTransport(Stream input, Stream output)`，可用于承载TCP套接字或其他流。
- 此仓库中尚未连接。
- HTTP/Streamable HTTP：尚未实现
- 当前使用的ModelContextProtocol .NET包（0.3.0-preview.4）不提供开箱即用的HTTP服务器传输。
- 计划（参见TODO）：添加`--transport http`、`--http-prefix`和`--http-api-key`，使用`HttpListener`托管，并将POST `/mcp`路由到MCP处理程序。稍后与MCP Streamable HTTP规范对齐。
## VS Code扩展
该MCP服务器的原始版本也作为VS Code扩展提供： [TIA-Portal MCP-Server](https://marketplace.visualstudio.com/items?itemName=JHeilingbrunner.vscode-tiaportal-mcp)。注意：该扩展捆绑v0.0.18，不包括此分支的额外工具。
