内容
# TwinCAT 3 MCP 服务器
MCP（模型上下文协议）服务器，允许 AI 代理与 Beckhoff TwinCAT 3 PLC 项目在三个独立的范围内协同工作：
1. **PLC 项目源代码**（基于文件）— 浏览/读取/搜索/编辑 POUs（`.TcPOU`）、GVLs（`.TcGVL`）、DUTs（`.TcDUT`）在磁盘上。可移植 - 在任何操作系统上都可工作。
2. **实时运行时**（ADS）— 连接到正在运行的 TwinCAT 运行时，读取/写入变量，调用方法，订阅更改，控制运行状态。
3. **XAE Shell 自动化**（COM）— 驱动 TwinCAT 工程 IDE：打开/构建/清理项目，读取构建错误，激活硬件配置，重启运行时。仅限 Windows，需要本地 TwinCAT XAE Shell 安装。
## 你可以要求它做的事情
连接后，代理可以执行以下几类任务，每个任务对应一个范围：
- **源代码**： "找到处理配方验证的 POU 并显示其实现" — 代理搜索并读取磁盘上的 POUs/GVLs/DUTs 源代码，并且（启用写入后）可以编辑声明/实现。
- **运行时**： "当前活动的配方结构的值是什么，如果 `MAIN.fbConveyor.eState` 发生变化，请通知我" — 代理读取/浏览实时的 ADS 符号并订阅值更改通知，并在样本到达时进行轮询。
- **自动化**： "构建项目并显示任何错误" — 代理驱动 XAE Shell 进行构建/清理并返回生成的错误列表。
任何更改状态的操作 — 符号写入、运行状态转换、构建、重启 — 都通过接下来描述的安全策略进行，因此即使启用写入，也仍然可以安全地进行探索。
每次更改任何内容的操作 — 源代码编辑、符号写入、状态转换、构建、重启 — 都由具有 `SafeMode` / 允许列表 / `dryRun` / `confirm` 和只追加审计日志的集中安全策略控制。在启用任何写入之前，请参阅 [`docs/SAFETY.md`](docs/SAFETY.md)。
## 设置（Windows 工程工作站）
自动化范围基于 COM 且仅限 Windows；运行时范围需要可达的 ADS 目标；源代码范围可移植。在工程工作站上运行整个服务器（与已安装的 XAE Shell 一起，带有本地/环回运行时）是同时支持这三个范围的自然选择。
> **仅限 Windows** — 软件包是为 `win-x64` 构建的自包含包。自动化范围需要 TwinCAT XAE Shell（COM/Windows），运行时范围需要可达的 ADS 目标。
### 先决条件
- **TwinCAT XAE Shell** 已在本地安装，带有本地或可达的 PLC 运行时
### 1. 查找 AMS Net ID（用于运行时范围）
在 TwinCAT 系统托盘图标中显示，或对于本地环回目标，使用 `127.0.0.1.1.1`。端口 `851` 是标准 PLC 运行时端口。
### 2. 安装
将服务器作为 .NET 工具安装（参见安装命令的 [NuGet 包](https://www.nuget.org/packages/Adonuu.TwinCatMcp)），这会在您的 PATH 上放置一个 `twincat-mcp` 二进制文件。
### 3. 配置
#### Claude 代码
```bash
claude mcp add twincat twincat-mcp --env Runtime__AmsNetId=127.0.0.1.1.1 --env Runtime__AmsPort=851 --env Safety__SafeMode=true --env Automation__ShowIde=true
```
启动时将 `Safety__SafeMode` 留在 `true` — 所有读取/浏览/搜索工具在此模式下都能完全正常工作；只有变更操作被阻止。有关完整的策略模型和推荐的分阶段启用写入的部署，请参阅 [`docs/SAFETY.md`](docs/SAFETY.md)。
## 许可证
[MIT](LICENSE) — 使用它、fork 它、发布它，只需保留版权声明。按原样提供，不保证；有关完整文本，请参阅 [`LICENSE`](LICENSE) 文件。
