Skip to main content
Glama
README.md
# Xinje TouchWin MCP

信捷 TouchWin Pro 的本地 MCP stdio 适配器。用于已登记副本的页面检查、有限属性修改,以及依赖本机 TouchWin 的原生保存、离线编译和重开读回。

本项目从现用 WAG 工具中的 TouchWin 适配器独立提取。**这是实验性工具,不是信捷官方 SDK,也不是通用触摸屏自动开发平台。** 不连接 PLC、不下载、不操作实体设备。厂商软件、DLL、厂商样例、客户工程、业务图片和本机运行记录均不随仓库分发。

English: A local stdio MCP adapter for bounded offline operations on registered TouchWin Pro project copies. Native operations require a separately installed, licensed vendor runtime. This experimental project is not affiliated with Xinje. See [capability boundaries](docs/CAPABILITIES.md).

## 当前范围

| 能力 | 公开版状态 |
|---|---|
| 未加密 `.xjp` ZIP/JSON 页面与控件检查 | 可用;文件级检查 |
| 现有本地地址、显示文字、已有跳转目标修改 | 可用;要求原值匹配,限制为登记副本 |
| 比较、备份恢复、人工保存后的差异审计 | 可用;不等于厂商验收 |
| 原生页面读取、保存/编译/重开闭环 | Windows 可选;需本机厂商软件和已登记种子 |
| 从六控件样例复制新页、有限已有只读 PLC 引用替换 | 历史有限样例有验证;公开版需使用者重新验证 |
| 固定背景图片导入 | 接口保留,公开版禁用;原固定素材属于业务工程 |
| 小数位写入、完整页面生成、在线操作 | 不支持或禁用 |

`capabilities` 中的历史 `PASSED` 字样只描述原开发环境的限定样例,**不代表当前安装、当前工程或本次公开版本通过原生验收**。本次发布的测试范围见 [验证说明](docs/VALIDATION.md)。

## 安装

需要 Python 3.12 或更高版本。原生能力还需要 Windows、x86 .NET Framework 编译器和自行安装的 TouchWin Pro。原适配器针对 `2.4.1.260820r` 开发;其他版本尚未验证。

```powershell
git clone https://github.com/522635710al-bot/xinje-touchwin-mcp.git
cd xinje-touchwin-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\touchwin-tool.exe capabilities
```

原生能力的 Python 依赖通过 `pip install ".[native]"` 安装。仓库包含 C# 适配源码,不包含编译产物及其厂商依赖。仅运行文件工具不需要启动厂商软件。

## MCP 连接

将 [examples/mcp.json](examples/mcp.json) 中的 Python 路径改为实际虚拟环境路径,按所用 MCP 客户端的配置格式接入。命令为 `python -m touchwin_mcp`,只使用本机 stdio,没有 HTTP 监听端口。

环境变量在启动前设置:

| 变量 | 默认值 / 说明 |
|---|---|
| `TOUCHWIN_MCP_HOME` | Windows 为 `%LOCALAPPDATA%/xinje-touchwin-mcp`;其他系统为用户 `.local/share` 下同名目录 |
| `TOUCHWIN_MCP_RUNTIME` | 状态目录下 `runtime`;只用于历史固定副本路线 |
| `TOUCHWIN_MCP_STAGE` | 系统临时目录下 `WAG_TouchWin_NativeCycles` |
| `TOUCHWIN_MCP_REGISTRY` | 状态目录下 `native/registry.json`;原生种子/副本登记表 |

不要将状态目录放进 Git 仓库。MCP 参数只接受 ID 和有限字段,不接收任意工程路径或脚本。

## 文件工具快速使用

使用自己有权使用的**未加密示例副本**,先在本机显式登记。此命令不会改写源文件。

```powershell
$env:TOUCHWIN_MCP_HOME = 'C:\touchwin-mcp-state'
.\.venv\Scripts\touchwin-register-source.exe --source-id installed_template --source 'C:\samples\sample.xjp'
'{"copy_id":"tw_demo","source_id":"installed_template"}' | Set-Content -Encoding utf8 create.json
.\.venv\Scripts\touchwin-tool.exe create_copy --request-file create.json
'{"copy_id":"tw_demo"}' | Set-Content -Encoding utf8 inventory.json
.\.venv\Scripts\touchwin-tool.exe inventory --request-file inventory.json
```

先读取真实控件名和原值,再填写 [patch.json](examples/patch.json)。示例中的 `DemoLabel`/`Ready` 是合成值,不保证存在于你的工程。

```powershell
.\.venv\Scripts\touchwin-tool.exe patch --request-file examples/patch.json
```

文件写入成功只表示 JSON 差异和读回检查通过;仍须用厂商软件确认保存、编译、显示和功能。`AESENC`、加密页、小数位及不兼容绑定会被拒绝,不进行解密。

## 原生工具

按 [原生配置说明](docs/NATIVE_SETUP.md) 准备自有运行时副本、编译 C# 辅助程序并登记已人工编译的种子。原生操作使用不切换的私有桌面;不注入鼠标、键盘或剪贴板输入。源码中的历史厂商方法与序列化字段不是稳定公共 API,版本改变时可能失效。

## 开发与测试

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```

测试使用运行时生成的合成数据,不包含客户工程。CI 不启动 TouchWin 或设备。修改后需要区分 Python 检查、C# 编译、真实厂商闭环和实体设备验证。

## 许可证与依赖

本仓库自有代码采用 [MIT License](LICENSE)。TouchWin、其 DLL、厂商样例及第三方库遵守各自许可证,MIT 不授予这些软件的再分发权。依赖与发布排除范围见 [第三方说明](THIRD_PARTY_NOTICES.md)。