内容
# TIA-Portal MCP 服务器
连接到西门子 TIA Portal 的 MCP 服务器。
由 **Paulo Leal Taveira** 维护 — [heilingbrunner/tiaportal-mcp](https://github.com/heilingbrunner/tiaportal-mcp) 的分支，带有额外的修复和扩展。
## 功能
- 连接到 TIA Portal 实例
- 浏览和交互 TIA Portal 项目
- 在 VS Code 中执行基本项目操作
## 要求
- 已安装 **.net Framework 4.8**
- 已安装并运行 **西门子 TIA Portal V20** 在您的机器上
- 检查在 `环境变量/用户变量 for 用户 <名称>` 中，变量 `TiaPortalLocation` 是否设置为 `C:\Program Files\Siemens\Automation\Portal V20`
- 用户必须在 Windows 用户组 `Siemens TIA Openness` 中
## TIA-Portal 版本
- **V20** 是默认版本。
- 早期版本也支持，但必须使用 `--tia-major-version` 参数指定版本。
- 通过 `ExportAsDocuments`/`ExportBlocksAsDocuments` 导出为文档 (.s7dcl/.s7res) 需要 TIA Portal V20 或更新版本。
- 通过 `ImportFromDocuments`/`ImportBlocksFromDocuments` 从文档 (.s7dcl/.s7res) 导入也需要 TIA Portal V20 或更新版本。
## 已知限制
- 截至 2025-09-02：从 SIMATIC SD 文档导入梯形图 (LAD) 块需要伴随的 `.s7res` 文件包含所有项目的 en-US 标签；否则导入可能会失败。这是 TIA Portal Openness 中的已知限制/错误。
- `ExportBlock` 需要完全限定的 `blockPath`，例如 `组/子组/名称`。如果仅提供名称，MCP 服务器将返回 `InvalidParams`，并可能包含对可能的全路径的建议。
## 测试
- 查看 `tests/TiaMcpServer.Test/README.md` 以获取环境先决条件和测试资产设置。
- 标准命令：`dotnet test`（从存储库根目录运行）。
- 测试执行策略：提供运行测试，但仅在用户明确确认后执行。详细信息请参见 `AGENTS.md`。
## 贡献
- 查看 `agents.md` 以获取有关使用代理助手和测试执行策略的指南（仅在用户明确确认后提供运行测试）。
## 错误处理（导出块）
- 门户层抛出 `PortalException`，带有简短消息和 `PortalErrorCode`（例如，NotFound、ExportFailed），并在导出失败时在 `Exception.Data` 中附加 `softwarePath`、`blockPath`、`exportPath`，同时保留 `InnerException`。
- MCP 层将这些映射到 `McpException` 代码。对于 `ExportFailed`，它包含来自底层错误的简洁原因；对于 `NotFound`，它返回 `InvalidParams`，并可能建议可能的完整块路径，如果提供了裸名称。
- 一致性要求：TIA Portal 永远不会导出不一致的块/类型。单个导出返回 `InvalidParams`，并附有消息，提示首先编译。批量导出跳过不一致的项目，并将它们返回在 `Inconsistent` 列表中，与 `Items` 并列。
- 标准化：异常上下文元数据在门户方法的单个 catch 中附加，就在重新抛出之前，而不是在内联抛出站点。参见 `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 规范对齐。
## Copilot 聊天
- 示例 mcp.json，当使用 VS Code 扩展 [TIA-Portal MCP-Server](https://marketplace.visualstudio.com/items?itemName=JHeilingbrunner.vscode-tiaportal-mcp) 和 TIA-Portal V18 时
```json
{
"servers": {
"vscode-tiaportal-mcp": {
"command": "c:\\Users\\<用户>\\.vscode\\extensions\\jheilingbrunner.vscode-tiaportal-mcp-<版本>\\srv\\net48\\TiaMcpServer.exe",
"args": [
"--tia-major-version",
"18"
],
"env": {}
}
}
}
```
## Claude 桌面
- 创建/编辑以添加/删除服务器到 `C:\Users\<用户>\AppData\Roaming\Claude\claude_desktop_config.json`：
```json
{
"mcpServers": {
"vscode-tiaportal-mcp": {
"command": "<路径到>\\TiaMcpServer.exe",
"args": [],
"env": {}
}
}
}
```
