FT Optix MCP

ftx-mcp

与 FactoryTalk Optix 项目对话。 ftx-mcp 将 AI 工具（桌面应用、Cowork、Code，或任何 MCP 客户端）连接到 Windows 计算机上的 FactoryTalk Optix Studio，让你只需描述需求，就能构建和修改 HMI 屏幕：

“在 Screen 1 上添加一个写着 ‘Hello Optix’ 的标题，并给我看看。”

“将该标签的可见性绑定到 Model/PumpRunning。”

“看起来没问题。启动模拟器并验证一下。”

你的大模型会直接在已打开的 Studio 项目中编写更改、运行模拟器，并查看渲染后的运行时画面以确认更改生效。它是开发和测试助手：部署到硬件仍须由你在 Studio 自带的 Deploy 对话框中完成。除大模型调用外，所有操作都在你的计算机本地运行。无需云服务，也无需 API 密钥；智能能力由你选择的大模型提供。

博客文章

安装（10 分钟）

要求：Windows 11、FactoryTalk Optix Studio 1.7.x，以及 Claude Cowork 这类 MCP 客户端。此外还需要 .NET SDK（8 或更高版本），供 build_check 使用（如果没有，build_check 会返回 no_dotnet）；Google Chrome（用于 CDP 验证循环；可通过 setup.ps1 -NoCdp 跳过）；如果使用 Claude Desktop Microsoft Store 版本的连接器路径，还需要 Node.js（winget install OpenJS.NodeJS.LTS；配置使用 npx mcp-remote）。安装程序会通过 winget 自动安装 Tesseract OCR，用于无需视觉令牌的文本工具（可通过 -NoOcr 跳过；其他功能仍可正常使用），并在 venv 中安装用于像素差异比较的 Pillow（硬性依赖）。

请在普通 PowerShell 窗口中运行 setup.ps1，不要在打包应用内部托管的 shell 中运行，例如 Claude Desktop 的 Store 版本；该版本会虚拟化 %LOCALAPPDATA% 写入操作（安装程序现在会检测这种情况并拒绝运行）。如果下载的是 ZIP 而非克隆的仓库，请先运行 Get-ChildItem -Recurse | Unblock-File。

如果 setup.ps1（或任何 bootstrap\*.ps1）完全无法运行，并出现脚本执行错误或“禁止运行脚本”错误，说明计算机的执行策略阻止了未签名脚本。仅对当前窗口解除限制——无需管理员权限，也不会永久更改策略——然后重新运行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

git clone https://github.com/asqi-carter/ftx-mcp.git
cd ftx-mcp
.\bootstrap\setup.ps1                                  # install (does not start anything)
.\bootstrap\services.ps1 start                         # start the service + cdp chrome
.\bootstrap\services.ps1 status                        # verify health
http://127.0.0.1:8765/ui                               # health dashboard

**身份验证：**默认安装仅监听 loopback，且关闭身份验证——安装程序不会提示输入信息，你自己的计算机上也不需要令牌。绑定到局域网是唯一需要身份验证的情况：安装时使用 .\bootstrap\setup.ps1 -EnableAuth（参见 docs/security.md）。如果界面/API 意外要求 bearer 令牌，说明之前的安装启用了身份验证——重新运行安装程序并添加 -NoAuth 即可清除。

要移除安装（或在全新重装前重置）： .\bootstrap\uninstall.ps1 会停止并注销计划任务，并清理任何残留的 CDP chrome；添加 -All 还会删除状态（已签发的令牌、chrome 配置文件、已保存的身份验证选项）和 venv。

pip / 注册表安装

pip install ftx-mcp 会安装该服务及其依赖项（包括 Pillow，现在是硬性依赖；ftx-mcp[visual] 仍作为空 extra 保留，以兼容旧说明）。wheel 还包含创作技能（skills/*/SKILL.md）、Studio 桥接源代码（StudioMCPBridge.cs）和 /ui 控制面板，因此无需检出仓库即可使用技能工具和 optix_bridge_arm 桥接同步；检出仓库的安装方式仍会读取仓库中的 skills/ 和 studio-bridge/。

通过 pip 安装不会获得以下内容，你仍需手动完成这些操作（参见 docs/runbook.md）：Studio、Tesseract OCR、用于 CDP 循环的 Chrome、计划任务/服务注册、身份验证设置以及 BridgeTemplate 刷新。通过检出仓库运行 bootstrap\setup.ps1 仍是受支持的 Windows 安装方式。

如果没有检出仓库，但需要获取项目或模板的桥接源代码，可以从正在运行的服务中获取：

Invoke-WebRequest http://127.0.0.1:8765/bridge-source -OutFile StudioMCPBridge.cs

GET /bridge-source 会以 text/plain 返回随包提供的文件，并附带 X-Ftx-Mcp-Version 标头。

升级

要升级检出安装（例如从 1.0.8 升级到 1.0.9），请在检出目录中打开普通 PowerShell 窗口，按顺序执行以下五个步骤：

1. bootstrap\services.ps1 stop
2. git pull（或替换检出目录）
3. bootstrap\uninstall.ps1 -PurgeVenv
4. bootstrap\setup.ps1
5. bootstrap\services.ps1 start

你的状态、机密信息和日志位于 %LOCALAPPDATA%\ftx-mcp\，在此过程中会保留 （-PurgeVenv 只会移除虚拟环境）。

• **现有项目：**每个现有项目首次运行 optix_bridge_arm 时，都会将其桥接源代码同步为随附版本，并在 ProjectFiles\.ftx-mcp-backups\ 下备份先前版本。
• **BridgeTemplate：**按照 docs/runbook.md 中的手动复制步骤，刷新已注册的 BridgeTemplate。使用旧模板创建的项目会在首次运行 arm 时同步。
• **pip install --upgrade 不受支持。**它不会升级检出安装：它可能会提高 pip 报告的版本，但服务仍会运行检出目录中的代码。请使用上述五个步骤。

另请参阅 docs/release-notes-v1.0.9.md。

启动 Studio Bridge（5 分钟）

1. 一次性桥接设置（每个项目）：在 Studio 项目树中，右键单击 NetLogic → 添加新的 DesignTime NetLogic，并命名为 StudioMCPBridge，双击它以打开 C# 编辑器，然后粘贴 studio-bridge/StudioMCPBridge.cs （请确保在代码编辑器中重新生成，或在 Studio 中保存以触发重新生成）
2. 设置项目：每次 Studio 会话执行一次；右键单击 StudioMCPBridge → SetupProject → 这只会添加一个 webui，以便通过 localhost:8081 进行验证访问
3. 启动桥接：每次 Studio 会话执行一次；右键单击 StudioMCPBridge → StartBridge → 接受 Studio 的 一次性安全提示。
4. 验证桥接运行状况：Studio Output 会显示 listening on http://127.0.0.1:8768（桥接）。服务仪表板 http://127.0.0.1:8765/ui 也会显示桥接状态。

Cowork（5 分钟）

要求：MCP 服务和桥接正在运行。已下载 Claude 桌面应用。

cd ftx-mcp                   # install + start the service
.\bootstrap\setup-mcp-client.ps1 -WriteConfig          # adds as a connector to desktop app

重启 Claude Desktop（你可能需要在任务管理器中结束任务才能彻底重启），然后让 Claude “run optix_status(action='doctor')”——它会报告所有缺失项，并为每项提供通俗易懂的修复方法。 在设置 > 连接器中，你可以调整各项工具的权限。

Claude Code（5 分钟）

ftx-mcp 通过 streamable-HTTP 在 http://127.0.0.1:8766/mcp 提供 MCP 服务。

要求：MCP 服务运行正常，且可在 cli 中访问 claude

claude mcp add --transport http ftx-mcp http://127.0.0.1:8766/mcp

然后在 Claude Code 中运行 /mcp，并确认 ftx-mcp 显示为已连接。

Visual Studio Code（5 分钟）

创建或打开 .vscode/mcp.json 并添加：

{
  "servers": {
    "ftx-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8766/mcp"
    }
  }
}

你的第一次修改

1. 请求进行一项修改，例如：“使用 ftx mcp，在 MainWindow 上添加一个启动和停止按钮，用于切换 Model/MotorRun；再添加一个文本为 ‘MOTOR RUNNING’、可见性与 MotorRun 绑定的标签，并验证其是否正常工作。”
2. 观看它运行：创作 → 仿真器预览 → 截图 → 确认效果无误后，像往常一样从 Studio 将其部署到硬件。

功能

• 创作组件、属性、绑定、计算表达式、事件、翻译和多屏导航——直接在已打开的 Studio 项目中进行。
• 运行 Studio 内置的模拟器（按 F5 键），并读取运行时日志。
• 验证 Web UI：查看屏幕截图、点击按钮和选项卡、在字段中输入内容。
• 交由你发布：预览效果符合预期后，你照常从 Studio 部署。本发行版仅运行模拟器。

完整工具列表（默认包含 36 个工具——可通过门控环境变量添加更多工具——并提供相同功能的纯 HTTP 接口，供脚本和 CI 使用）见 docs/tool-reference.md。 **节省令牌：**每张屏幕截图约消耗 1–2k 个视觉令牌；optix_observe 的 OCR 模式（read_text、find_text、diff）可将大多数检查转为免费的文本读取——工作流详见 optix-blind-authoring 和 optix-visual-regression 操作手册（安装程序会自动安装 tesseract；使用 -NoOcr 可选择不启用）。

服务器内置 19 个创作操作手册（涵盖导航、绑定控件、样式和表达式）——Claude 可通过 optix_list_skills / optix_get_skill 发现这些手册，因此每个连接的客户端无需任何设置即可使用。（在 Claude Code 中，这些手册也会原生加载为技能。）

安全与防护措施

• **仅限本地。**服务绑定到 127.0.0.1，不会与本机以外的任何对象通信。可选的 bearer-token 身份验证会在绑定到任何 LAN 地址之前强制执行。
• **默认只读。**每个工具都带有 MCP readOnlyHint / destructiveHint 注释（由测试锁定为契约），因此 MCP 宿主可以自动批准读取操作，并对写入操作进行门控。
• **依靠写入门控，而非寄希望于安全。**未声明的属性、数组写入、重复名称和不安全的重新设定父级操作都会被拒绝，并返回类型化错误；组合操作失败时会回滚。Studio 打开项目时，项目文件读取（optix_read_file）会被拒绝；实时模型的读取和写入会通过桥接程序进行。
• **经过审计。**每次模型修改都会将一条 JSON 记录追加到本地审计日志（%LOCALAPPDATA%\ftx-mcp\logs\audit.jsonl），记录操作内容、时间和结果。
• **发布由你掌控。**预览绝不会触及运行时；硬件部署只能从 Studio 进行。本发行版仅通过模拟器执行设计时编辑和测试。

完整的安全防护措施（包括提示词注入攻击面分析）见 SECURITY.md。

文档

运行手册	首次使用，逐步说明
工具参考	所有 MCP 工具和 HTTP API
架构	各部分如何协同工作
故障排除	按症状索引的解决方法
安全	身份验证、端口及通信对象

兼容性

已在 Windows 11 上搭配 FactoryTalk Optix Studio 1.7.x 和 Python 3.12 测试。 Optix CLI 的行为在不同主版本之间不保证契约稳定——请在生产环境中固定 Studio 版本。

许可证

MIT · © 2026 ASQI · 与 Rockwell Automation 无关联，也未获其认可。FactoryTalk Optix 是 Rockwell Automation, Inc. 的商标；本项目会调用本地安装的 Optix 二进制文件，但不会重新分发这些文件。详见 NOTICE。