keyshot-mcp 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to KeyShot MCP are documented in this file.
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-12
+
+### Added
+
+- `keyshot_sync_saved_scene`, which detects the newest saved `.bip`, copies it to
+  a collision-safe output, returns a content fingerprint, and optionally embeds a
+  preview.
+- Machine-readable interaction-mode diagnostics so Agents can explain that stable
+  tools work on saved scenes rather than an unsaved GUI session.
+- An original KeyShot MCP project mark and a clearer README introduction,
+  navigation, highlights, and bilingual positioning for easier recognition.
+
+### Changed
+
+- README, Agent Skill, and MCP workflow guidance now explain the tested KeyShot
+  Script Runner limitation and recommend the saved-scene synchronization workflow.
+
 ## [0.10.0] - 2026-08-11
 
 ### Added
@@ -22,5 +39,6 @@ All notable changes to KeyShot MCP are documented in this file.
 
 - Documented that scene metadata and preview images may be sent by an MCP client to its configured model provider.
 
-[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.9.1...v0.10.0

package/README.md

@@ -1,35 +1,79 @@
-# KeyShot MCP
-
-[![npm version](https://img.shields.io/npm/v/keyshot-mcp.svg)](https://www.npmjs.com/package/keyshot-mcp)
-[![CI](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-[English](#english) | [中文](#中文)
-
-> **Useful for your KeyShot workflow? Star the repository to help other designers discover it.**
->
-> **如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。**
+<p align="center">
+  <img src="assets/logo-lockup.png" width="620" alt="KeyShot MCP">
+</p>
+
+<p align="center">
+  <strong>Turn product-rendering requests into safe, repeatable KeyShot workflows.</strong><br>
+  <strong>将产品渲染需求转化为安全、可重复执行的 KeyShot 工作流。</strong>
+</p>
+
+<p align="center">
+  Inspect scenes, prepare product views, adjust materials, cameras and environments,
+  and return Agent-visible renders through local KeyShot headless scripting.<br>
+  检查场景、准备产品视图、调整材质、相机和环境，并通过本地 KeyShot headless 脚本将渲染结果返回给 Agent。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/keyshot-mcp"><img src="https://img.shields.io/npm/v/keyshot-mcp.svg" alt="npm version"></a>
+  <a href="https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml"><img src="https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/tools-19-55E6A5" alt="19 MCP tools">
+  <img src="https://img.shields.io/badge/MCP-Model_Context_Protocol-111827" alt="Model Context Protocol">
+  <img src="https://img.shields.io/badge/KeyShot-14.1_tested-00AEEF" alt="KeyShot 14.1 tested">
+  <img src="https://img.shields.io/badge/Node.js-20%2B-339933" alt="Node.js 20 or newer">
+  <img src="https://img.shields.io/badge/TypeScript-5.9-3178C6" alt="TypeScript 5.9">
+</p>
+
+<p align="center">
+  <a href="#quick-start-for-designers">Quick start</a> ·
+  <a href="#highlights">Highlights</a> ·
+  <a href="#common-workflows">Workflows</a> ·
+  <a href="#tools">Tools</a> ·
+  <a href="#configuration">Configuration</a>
+</p>
+
+<p align="center"><a href="#english">English</a> · <a href="#中文">简体中文</a></p>
+
+<p align="center">
+  <strong>Useful for your KeyShot workflow? Star the repository to help other designers discover it.</strong><br>
+  <strong>如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。</strong>
+</p>
 
 KeyShot MCP connects an MCP-compatible AI agent to a licensed KeyShot installation
-on the same computer. It can inspect scenes, import models, apply materials, set
-cameras and environments, save scene copies, and render images through KeyShot
-headless scripting. KeyShot file processing stays local; however, an MCP client may
-send tool results, scene metadata, or embedded previews to its configured model
+on the same computer. KeyShot file processing stays local; however, an MCP client
+may send tool results, scene metadata, or embedded previews to its configured model
 provider. See [Security](SECURITY.md) before using confidential work.
 
 ![KeyShot MCP workflow](assets/workflow.svg)
 
 ## English
 
+### Highlights
+
+- **Start with a request, not a render-settings checklist.** Use one product tool
+  for model import, object materials, camera, environment, scene copy, and output.
+- **See before committing.** Bounded PNG previews are returned directly to the
+  Agent for composition, material, and lighting feedback.
+- **Keep source scenes protected.** Editing workflows write controlled copies and
+  reject output paths outside the configured safe directory by default.
+- **Continue from the latest save.** Saved-scene sync detects real file changes,
+  creates a collision-safe copy, and avoids duplicate work with fingerprints.
+- **Use focused controls when needed.** Nineteen documented tools cover inspection,
+  presets, cameras, materials, environments, render queues, and all-camera output.
+
+> [!NOTE]
+> Tested on Windows 11 with KeyShot Studio 2025 / KeyShot 14.1. KeyShot and a valid
+> license are required and are not included with this independent project.
+
 ### Quick start for designers
 
 The easiest setup is to send this prompt to an agent that can edit your MCP
 configuration:
 
 ```text
-Install KeyShot MCP 0.10.0 and configure it in my MCP client.
+Install KeyShot MCP 0.11.0 and configure it in my MCP client.
 
-1. Use: npx -y keyshot-mcp@0.10.0
+1. Use: npx -y keyshot-mcp@0.11.0
 2. Find my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE to its full path.
 3. Keep outputs in the default KeyShot MCP Outputs folder unless I choose another safe folder.
 4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
@@ -55,9 +99,41 @@ from C:\models\speaker.obj.
   they are not currently verified by this project.
 - KeyShot, its license, materials, and environments are not included.
 
+### Why the stable release does not control the open KeyShot window
+
+The stable server works on saved scene files through KeyShot headless scripting;
+it does not control the currently open, unsaved KeyShot GUI session. This is a
+boundary of the public KeyShot scripting execution model, not an omitted MCP
+connection. KeyShot's Script Runner keeps a GUI script active until that script
+returns. In our Live Companion prototype, keeping a bridge alive also kept the
+Script Runner open and blocked normal interaction with the KeyShot window.
+
+Calling `lux.sync()` can flush pending KeyShot operations, but it does not provide
+a documented background service, GUI event callback, or plugin lifecycle that can
+safely host a persistent MCP bridge. Calling `lux` from an arbitrary worker thread
+would also risk unsafe access to the scene. For that reason, the project does not
+present the experimental bridge as production-ready realtime control.
+
+For a reliable workflow, save the scene first. The Agent can inspect or edit a
+safe copy through headless KeyShot, return a preview, and preserve the original
+file. True realtime GUI control can be reconsidered if KeyShot exposes a supported
+non-blocking GUI extension or main-thread callback API.
+
+Use `keyshot_sync_saved_scene` for the closest stable alternative to realtime
+collaboration. Give it a saved `.bip` file or one folder containing `.bip` files.
+It selects the newest saved scene, computes a content fingerprint, copies it to a
+collision-safe output name, and returns an embedded preview by default. Pass the
+returned fingerprint on the next call; if the user has not saved a new change,
+the tool reports `changed: false` without creating another copy or render.
+
+```text
+I saved my KeyShot scene in C:\projects\speaker. Sync the newest .bip from that
+folder, show me a preview, and do not overwrite the original scene.
+```
+
 ### Install
 
-The current release is `0.10.0`.
+The current release is `0.11.0`.
 
 #### Run with npx
 
@@ -68,7 +144,7 @@ No global npm installation is required:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.10.0"],
+      "args": ["-y", "keyshot-mcp@0.11.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -80,7 +156,7 @@ No global npm installation is required:
 #### Install globally
 
 ```bash
-npm install -g keyshot-mcp@0.10.0
+npm install -g keyshot-mcp@0.11.0
 ```
 
 ```json
@@ -185,6 +261,7 @@ Lower-level render tools preserve their existing behavior when no preset is give
 | `keyshot_status`                | Diagnose local configuration, output access, presets, and KeyShot startup.    |
 | `keyshot_product_render`        | Prepare, save, and render a model or scene in one process.                    |
 | `keyshot_preview_render`        | Return a temporary or saved PNG directly to the Agent for visual review.      |
+| `keyshot_sync_saved_scene`      | Copy the newest saved scene safely, detect changes, and return a preview.     |
 | `keyshot_inspect_scene`         | List scene metadata, objects, cameras, materials, model sets, and references. |
 | `keyshot_list_cameras`          | Return saved camera names before a selected-camera render.                    |
 | `keyshot_render`                | Render one active or named camera.                                            |
@@ -203,7 +280,7 @@ Lower-level render tools preserve their existing behavior when no preset is give
 
 The server also exposes one MCP Prompt for product rendering and one MCP Resource
 describing the KeyShot headless workflow. The complete generated reference for
-all 18 tools is in [`docs/TOOLS.md`](docs/TOOLS.md). The bundled Agent Skill in
+all 19 tools is available in [`docs/TOOLS.md`](docs/TOOLS.md). The bundled Agent Skill in
 [`skills/keyshot-mcp`](skills/keyshot-mcp) teaches compatible agents how to install,
 diagnose, and use the server safely.
 
@@ -293,14 +370,29 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
 KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具结果、场景元数据或
 内嵌预览发送给它所配置的模型服务。处理保密项目之前请先阅读[安全说明](SECURITY.md)。
 
+### 核心特点
+
+- **从设计需求开始，而不是先填写一堆渲染参数。** 一个产品出图工具即可完成模型导入、
+  指定对象材质、相机、环境、场景副本和渲染输出。
+- **正式出图前先看预览。** 预览 PNG 会直接返回给 Agent，用于检查构图、材质和光线。
+- **保护源场景。** 编辑流程默认生成受控副本，并拒绝向安全输出目录之外写入文件。
+- **从最近一次保存继续。** 保存同步会识别真实文件变化、创建不重名副本，并用内容指纹
+  避免重复处理。
+- **需要精细控制时仍然可用。** 19 个工具覆盖场景检查、预设、相机、材质、环境、
+  渲染队列和全部相机出图。
+
+> [!NOTE]
+> 已实测 Windows 11 + KeyShot Studio 2025 / KeyShot 14.1。使用时需要另行安装并合法
+> 授权 KeyShot；本项目是独立开源项目，不包含 KeyShot 软件或许可证。
+
 ### 设计师快速开始
 
 最简单的安装方式，是把下面这段话发给能够修改 MCP 配置的 Agent：
 
 ```text
-请安装 KeyShot MCP 0.10.0，并配置到我的 MCP 客户端。
+请安装 KeyShot MCP 0.11.0，并配置到我的 MCP 客户端。
 
-1. 使用：npx -y keyshot-mcp@0.10.0
+1. 使用：npx -y keyshot-mcp@0.11.0
 2. 查找本机 keyshot_headless.exe，并把完整路径设置为 KEYSHOT_HEADLESS_EXE。
 3. 默认把结果保存在“文档/KeyShot MCP Outputs”，除非我明确选择其他安全目录。
 4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
@@ -324,9 +416,36 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 - 暴露相同脚本 API 的其他 KeyShot 版本可能可用，但本项目暂未完成实机验证。
 - 本项目不包含 KeyShot、许可证、官方材质或环境资源。
 
+### 为什么稳定版不能控制当前打开的 KeyShot 窗口
+
+稳定版通过 KeyShot headless 脚本处理已经保存的场景文件，不能直接控制 KeyShot
+窗口中尚未保存的当前会话。这是 KeyShot 现有公开脚本执行方式的边界，并不是 MCP
+连接功能遗漏。
+
+我们已经制作并实机测试过 Live Companion 原型。为了等待 Agent 指令，Bridge 脚本
+必须长期保持运行；但 KeyShot Script Runner 会一直等待脚本结束，导致脚本窗口持续
+占用并阻挡 KeyShot GUI 的正常交互。`lux.sync()` 只能同步待处理操作，公开文档没有
+提供可安全承载常驻 MCP Bridge 的后台服务、GUI 事件回调或插件生命周期。让普通后台
+线程直接调用 `lux` 也可能造成不安全的场景访问。因此，本项目没有把这个实验方案包装成
+可用于正式工作的“实时控制”。
+
+可靠的工作方式是先保存场景，再让 Agent 使用 headless KeyShot 检查或修改安全副本、
+返回预览并保留原文件。如果 KeyShot 后续公开非阻塞 GUI 扩展接口或主线程回调 API，
+本项目可以重新评估真正的实时 GUI 控制。
+
+`keyshot_sync_saved_scene` 是目前最接近实时协作、同时保持稳定的方案。向它提供一个已
+保存的 `.bip` 文件，或只包含当前项目场景的文件夹。工具会选择最近保存的场景、计算
+内容指纹、复制到不会重名的安全输出路径，并默认返回内嵌预览。下一次调用时传入上次的
+指纹；如果用户没有保存新的修改，工具会返回 `changed: false`，不会重复复制或渲染。
+
+```text
+我已经把 KeyShot 场景保存在 C:\projects\speaker。请同步这个文件夹中最新的 .bip，
+给我看预览，而且不要覆盖原场景。
+```
+
 ### 安装
 
-当前正式版本为 `0.10.0`。
+当前正式版本为 `0.11.0`。
 
 #### 使用 npx 免安装运行
 
@@ -335,7 +454,7 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.10.0"],
+      "args": ["-y", "keyshot-mcp@0.11.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -347,7 +466,7 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 #### 全局安装
 
 ```bash
-npm install -g keyshot-mcp@0.10.0
+npm install -g keyshot-mcp@0.11.0
 ```
 
 ```json
@@ -446,6 +565,7 @@ pnpm build
 | `keyshot_status`                | 检查本机配置、输出目录、预设和 KeyShot 启动状态。  |
 | `keyshot_product_render`        | 在一个进程中整理、保存并渲染模型或场景。           |
 | `keyshot_preview_render`        | 将临时或保留的 PNG 直接返回给 Agent 进行视觉检查。 |
+| `keyshot_sync_saved_scene`      | 安全同步最近保存的场景、检测变化并返回预览。       |
 | `keyshot_inspect_scene`         | 查看场景、对象、相机、材质、模型集和外部引用。     |
 | `keyshot_list_cameras`          | 返回场景中的相机名称。                             |
 | `keyshot_render`                | 渲染当前或指定相机。                               |
@@ -463,7 +583,7 @@ pnpm build
 | `keyshot_save_scene`            | 将场景保存到受控输出路径。                         |
 
 服务还提供一个产品渲染 MCP Prompt，以及一个说明 headless 工作流程的 MCP Resource。
-完整的 18 个工具参考由代码自动生成在 [`docs/TOOLS.md`](docs/TOOLS.md)。
+完整的 19 个工具参考由代码自动生成在 [`docs/TOOLS.md`](docs/TOOLS.md)。
 [`skills/keyshot-mcp`](skills/keyshot-mcp) 中的 Agent Skill 会指导兼容的 Agent 安装、
 诊断并安全使用这些工具。
 

package/dist/diagnostics.js

@@ -74,6 +74,13 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
             availableFunctionCount: availableFunctions.length,
             capabilities: capabilitySummary(availableFunctions),
             serverVersion: VERSION,
+            interaction: {
+                mode: "saved-scene-headless",
+                realtimeGuiControl: false,
+                requiresSavedScene: true,
+                recommendedSyncTool: "keyshot_sync_saved_scene",
+                reason: "Persistent GUI scripts keep KeyShot Script Runner active and block normal GUI interaction; the documented scripting API does not expose a supported non-blocking bridge lifecycle.",
+            },
             ready,
             config: {
                 keyshotHeadlessExe: config.keyshotHeadlessExe,

package/dist/save-sync.js

@@ -0,0 +1,203 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { normalizeOutputPath } from "./output-paths.js";
+import { renderPreview } from "./preview.js";
+import { localFailure, toolResponse } from "./result.js";
+import { syncSavedSceneInputSchema } from "./schemas.js";
+export async function syncSavedScene(config, rawArgs, previewFn = renderPreview) {
+    let copiedPath;
+    try {
+        const args = syncSavedSceneInputSchema.parse(rawArgs);
+        const sourcePath = await resolveSavedScene(args.sourcePath);
+        const sourceBefore = await describeFile(sourcePath);
+        if (args.previousFingerprint === sourceBefore.fingerprint) {
+            return toolResponse({
+                ok: true,
+                data: {
+                    changed: false,
+                    sourcePath,
+                    fingerprint: sourceBefore.fingerprint,
+                    size: sourceBefore.size,
+                    modifiedAt: sourceBefore.modifiedAt,
+                    synchronizedScene: null,
+                    previewEmbedded: false,
+                },
+                outputFiles: [],
+                warnings: [],
+                keyshotStdoutTail: "",
+                error: null,
+            });
+        }
+        copiedPath = args.outputScenePath
+            ? await normalizeOutputPath(config, args.outputScenePath)
+            : await allocateSyncPath(config, sourcePath);
+        if (await exists(copiedPath)) {
+            throw new Error(`Output already exists and overwrite is false: ${copiedPath}`);
+        }
+        if (samePath(sourcePath, copiedPath)) {
+            throw new Error("The synchronized scene copy must differ from sourcePath.");
+        }
+        await fsp.mkdir(path.dirname(copiedPath), { recursive: true });
+        await fsp.copyFile(sourcePath, copiedPath, fs.constants.COPYFILE_EXCL);
+        const sourceAfter = await describeFile(sourcePath);
+        if (sourceAfter.size !== sourceBefore.size ||
+            sourceAfter.modifiedMs !== sourceBefore.modifiedMs ||
+            sourceAfter.fingerprint !== sourceBefore.fingerprint) {
+            await fsp.rm(copiedPath, { force: true });
+            copiedPath = undefined;
+            throw new Error("The KeyShot scene changed while it was being copied. Wait for saving to finish, then retry.");
+        }
+        const baseData = {
+            changed: true,
+            sourcePath,
+            fingerprint: sourceBefore.fingerprint,
+            size: sourceBefore.size,
+            modifiedAt: sourceBefore.modifiedAt,
+            synchronizedScene: copiedPath,
+        };
+        if (args.includePreview === false) {
+            return toolResponse({
+                ok: true,
+                data: { ...baseData, previewEmbedded: false },
+                outputFiles: [copiedPath],
+                warnings: [],
+                keyshotStdoutTail: "",
+                error: null,
+            });
+        }
+        const preview = (await previewFn(config, {
+            scenePath: copiedPath,
+            camera: args.camera,
+            width: args.width,
+            height: args.height,
+            samples: args.samples,
+            maxTimeSeconds: args.maxTimeSeconds,
+        }));
+        const previewResult = preview.structuredContent;
+        const combined = {
+            ...previewResult,
+            data: {
+                ...baseData,
+                previewEmbedded: previewResult.ok,
+                preview: previewResult.data && typeof previewResult.data === "object"
+                    ? previewResult.data.preview
+                    : null,
+            },
+            outputFiles: uniquePaths([copiedPath, ...previewResult.outputFiles]),
+        };
+        return {
+            ...preview,
+            content: [
+                { type: "text", text: JSON.stringify(combined, null, 2) },
+                ...preview.content.filter((item) => item.type === "image"),
+            ],
+            structuredContent: { ...combined },
+            isError: !combined.ok,
+        };
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        const suggestions = syncSuggestions(message);
+        return toolResponse(localFailure(message, {
+            outputFiles: copiedPath ? [copiedPath] : [],
+            suggestions,
+        }));
+    }
+}
+export async function resolveSavedScene(sourcePath) {
+    const resolved = path.resolve(sourcePath);
+    let stat;
+    try {
+        stat = await fsp.stat(resolved);
+    }
+    catch {
+        throw new Error(`Saved KeyShot scene path not found: ${resolved}`);
+    }
+    if (stat.isFile()) {
+        if (!isBip(resolved))
+            throw new Error(`Saved KeyShot scene must use the .bip extension: ${resolved}`);
+        return resolved;
+    }
+    if (!stat.isDirectory())
+        throw new Error(`Saved KeyShot scene path is not a file or directory: ${resolved}`);
+    const candidates = await Promise.all((await fsp.readdir(resolved, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && isBip(entry.name))
+        .map(async (entry) => {
+        const filePath = path.join(resolved, entry.name);
+        return { filePath, stat: await fsp.stat(filePath) };
+    }));
+    candidates.sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs ||
+        left.filePath.localeCompare(right.filePath));
+    if (!candidates[0])
+        throw new Error(`No saved .bip scene was found in directory: ${resolved}`);
+    return candidates[0].filePath;
+}
+async function describeFile(filePath) {
+    const stat = await fsp.stat(filePath);
+    const hash = crypto.createHash("sha256");
+    await new Promise((resolve, reject) => {
+        const input = fs.createReadStream(filePath);
+        input.on("data", (chunk) => hash.update(chunk));
+        input.on("error", reject);
+        input.on("end", resolve);
+    });
+    const sha256 = hash.digest("hex");
+    return {
+        size: stat.size,
+        modifiedMs: stat.mtimeMs,
+        modifiedAt: stat.mtime.toISOString(),
+        sha256,
+        fingerprint: `sha256:${sha256}`,
+    };
+}
+async function allocateSyncPath(config, sourcePath) {
+    const stem = path.parse(sourcePath).name;
+    for (let sequence = 1; sequence < 10_000; sequence += 1) {
+        const suffix = sequence === 1 ? "" : `-${sequence}`;
+        const candidate = await normalizeOutputPath(config, `${stem}-synced${suffix}.bip`);
+        if (!(await exists(candidate)))
+            return candidate;
+    }
+    throw new Error("Could not find an available synchronized scene name after 9999 attempts.");
+}
+function syncSuggestions(error) {
+    const normalized = error.toLowerCase();
+    if (normalized.includes("changed while it was being copied")) {
+        return [
+            "Wait until KeyShot finishes saving the scene, then call keyshot_sync_saved_scene again.",
+        ];
+    }
+    if (normalized.includes("no saved .bip") ||
+        normalized.includes("not found")) {
+        return [
+            "Save the scene as a .bip file, then provide that file path or its containing folder.",
+        ];
+    }
+    return localFailure(error).suggestions ?? [];
+}
+function isBip(value) {
+    return path.extname(value).toLowerCase() === ".bip";
+}
+function samePath(left, right) {
+    const normalize = (value) => process.platform === "win32"
+        ? path.resolve(value).toLowerCase()
+        : path.resolve(value);
+    return normalize(left) === normalize(right);
+}
+async function exists(value) {
+    try {
+        await fsp.lstat(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function uniquePaths(values) {
+    return [...new Set(values)];
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/schemas.js

@@ -111,6 +111,45 @@ export const previewRenderInputSchema = previewRenderSchema.superRefine((value,
         });
     }
 });
+export const syncSavedSceneSchema = z.object({
+    sourcePath: requiredPath("Absolute path to a saved .bip scene or a directory whose newest .bip scene should be synchronized. Directories are searched only at their top level."),
+    previousFingerprint: z
+        .string()
+        .min(1)
+        .describe("Optional fingerprint returned by an earlier sync. When it still matches, no copy or preview is created.")
+        .optional(),
+    outputScenePath: optionalPath("Optional destination for the synchronized .bip copy inside KEYSHOT_OUTPUT_DIR. Existing explicit paths are never overwritten; when omitted, a collision-safe name is generated."),
+    includePreview: z
+        .boolean()
+        .describe("Whether to render and embed a temporary PNG from the synchronized copy. Defaults to true.")
+        .optional(),
+    camera: z
+        .string()
+        .min(1)
+        .describe("Optional saved camera name for the embedded preview. Omit to use the scene's active camera.")
+        .optional(),
+    width: previewRenderSchema.shape.width,
+    height: previewRenderSchema.shape.height,
+    samples: previewRenderSchema.shape.samples,
+    maxTimeSeconds: previewRenderSchema.shape.maxTimeSeconds,
+});
+export const syncSavedSceneInputSchema = syncSavedSceneSchema.superRefine((value, context) => {
+    if (value.samples !== undefined && value.maxTimeSeconds !== undefined) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Choose either samples or maxTimeSeconds, not both.",
+            path: ["maxTimeSeconds"],
+        });
+    }
+    if (value.outputScenePath !== undefined &&
+        !value.outputScenePath.toLowerCase().endsWith(".bip")) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Synchronized outputScenePath must use the .bip extension.",
+            path: ["outputScenePath"],
+        });
+    }
+});
 export const batchRenderSchema = z.object({
     scenePath,
     outputDir: outputDirectory,

package/dist/server.js

@@ -10,7 +10,8 @@ import { VERSION } from "./version.js";
 import { applyRenderQuality } from "./quality.js";
 import { runKeyShotDiagnostics } from "./diagnostics.js";
 import { renderPreview } from "./preview.js";
-import { applyCameraPresetTool, applyMaterialPresetTool, applyMaterialTool, batchRenderTool, importModelTool, inspectSceneTool, listCameraPresetsTool, listCamerasTool, listMaterialPresetsTool, previewRenderTool, productRenderTool, registrationOptions, renderAllCamerasTool, renderQueueTool, renderTool, saveSceneTool, setCameraTool, setEnvironmentTool, statusTool, } from "./tools/catalog.js";
+import { syncSavedScene } from "./save-sync.js";
+import { applyCameraPresetTool, applyMaterialPresetTool, applyMaterialTool, batchRenderTool, importModelTool, inspectSceneTool, listCameraPresetsTool, listCamerasTool, listMaterialPresetsTool, previewRenderTool, productRenderTool, registrationOptions, renderAllCamerasTool, renderQueueTool, renderTool, saveSceneTool, setCameraTool, setEnvironmentTool, statusTool, syncSavedSceneTool, } from "./tools/catalog.js";
 import { applyMaterialSchema, applyMaterialPresetSchema, batchRenderInputSchema, productRenderSchema, renderQueueInputSchema, renderAllCamerasInputSchema, renderInputSchema, scenePathSchema, setCameraSchema, } from "./schemas.js";
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -34,6 +35,9 @@ export function createKeyShotServer(config = getConfig()) {
                     "2. The MCP client sends a structured tool call to this server.",
                     "3. This server runs a temporary Python script through KeyShot headless.",
                     "4. KeyShot writes images or scene files and returns structured JSON results.",
+                    "5. Stable tools operate on saved files; they do not attach to the currently open, unsaved KeyShot GUI session.",
+                    "6. Reason: a persistent bridge tested through KeyShot Script Runner keeps the runner active and blocks normal GUI interaction, while the documented scripting API does not expose a supported non-blocking GUI service or main-thread callback lifecycle.",
+                    "7. If realtime GUI control is requested, explain this boundary, ask the user to save the scene, and offer to process a safe copy and return a preview.",
                 ].join("\n"),
             },
         ],
@@ -89,6 +93,7 @@ export function createKeyShotServer(config = getConfig()) {
         ...args,
     })));
     server.registerTool("keyshot_preview_render", registrationOptions(previewRenderTool), async (args) => renderPreview(config, args));
+    server.registerTool("keyshot_sync_saved_scene", registrationOptions(syncSavedSceneTool), async (args) => syncSavedScene(config, args));
     server.registerTool("keyshot_render", registrationOptions(renderTool), async (args) => {
         const parsed = renderInputSchema.parse(args);
         return toolResponse(await runKeyShotSerialized(config, {

package/dist/tools/catalog.js

@@ -1,5 +1,5 @@
 import { keyShotResultSchema } from "../result.js";
-import { applyCameraPresetSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, batchRenderSchema, importModelSchema, listCameraPresetsSchema, listCamerasSchema, listMaterialPresetsSchema, previewRenderSchema, productRenderInputSchema, renderAllCamerasSchema, renderQueueSchema, renderSchema, saveSceneSchema, scenePathSchema, setCameraInputSchema, setEnvironmentSchema, } from "../schemas.js";
+import { applyCameraPresetSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, batchRenderSchema, importModelSchema, listCameraPresetsSchema, listCamerasSchema, listMaterialPresetsSchema, previewRenderSchema, productRenderInputSchema, renderAllCamerasSchema, renderQueueSchema, renderSchema, saveSceneSchema, scenePathSchema, setCameraInputSchema, setEnvironmentSchema, syncSavedSceneSchema, } from "../schemas.js";
 export const readOnlyAnnotations = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -62,6 +62,15 @@ export const previewRenderTool = defineTool({
     outputSchema: keyShotResultSchema,
     annotations: readOnly,
 });
+export const syncSavedSceneTool = defineTool({
+    name: "keyshot_sync_saved_scene",
+    group: "Inspection",
+    title: "Sync the latest saved KeyShot scene",
+    description: "Find a saved .bip file (or the newest .bip in one folder), detect whether it changed, copy it to a collision-safe output path, and optionally return an Agent-visible preview. This is the stable alternative to unsupported persistent GUI control.",
+    inputSchema: syncSavedSceneSchema,
+    outputSchema: keyShotResultSchema,
+    annotations: writesOutput,
+});
 export const renderTool = defineTool({
     name: "keyshot_render",
     group: "Rendering",
@@ -185,6 +194,7 @@ export const TOOL_CATALOG = [
     inspectSceneTool,
     listCamerasTool,
     previewRenderTool,
+    syncSavedSceneTool,
     renderTool,
     renderQueueTool,
     batchRenderTool,

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.10.0";
+export const VERSION = "0.11.0";

package/docs/TOOLS.md

@@ -2,7 +2,7 @@
 
 > Generated from `src/tools/catalog.ts`. Do not edit this file by hand.
 
-KeyShot MCP exposes 18 tools. All tools return JSON text and structured content using the common result schema.
+KeyShot MCP exposes 19 tools. All tools return JSON text and structured content using the common result schema.
 
 ## Diagnostics
 
@@ -180,6 +180,26 @@ Safety: read-only; non-destructive; local only.
 | ----------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
 | `scenePath` | Yes      | string | Absolute path to an existing KeyShot scene file to open. Input files may be outside the configured output directory. |
 
+### `keyshot_sync_saved_scene`
+
+**Sync the latest saved KeyShot scene**
+
+Find a saved .bip file (or the newest .bip in one folder), detect whether it changed, copy it to a collision-safe output path, and optionally return an Agent-visible preview. This is the stable alternative to unsupported persistent GUI control.
+
+Safety: writes output; potentially destructive; local only.
+
+| Parameter             | Required | Type    | Description                                                                                                                                                                     |
+| --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sourcePath`          | Yes      | string  | Absolute path to a saved .bip scene or a directory whose newest .bip scene should be synchronized. Directories are searched only at their top level.                            |
+| `previousFingerprint` | No       | string  | Optional fingerprint returned by an earlier sync. When it still matches, no copy or preview is created.                                                                         |
+| `outputScenePath`     | No       | string  | Optional destination for the synchronized .bip copy inside KEYSHOT_OUTPUT_DIR. Existing explicit paths are never overwritten; when omitted, a collision-safe name is generated. |
+| `includePreview`      | No       | boolean | Whether to render and embed a temporary PNG from the synchronized copy. Defaults to true.                                                                                       |
+| `camera`              | No       | string  | Optional saved camera name for the embedded preview. Omit to use the scene's active camera.                                                                                     |
+| `width`               | No       | number  | Preview width in pixels. Defaults to 960; allowed range is 64 to 1920.                                                                                                          |
+| `height`              | No       | number  | Preview height in pixels. Defaults to 540; allowed range is 64 to 1080.                                                                                                         |
+| `samples`             | No       | number  | Preview render samples. Defaults to 16 unless maxTimeSeconds is provided; maximum is 64.                                                                                        |
+| `maxTimeSeconds`      | No       | number  | Time-based preview limit in seconds. Replaces the default sample mode and cannot be combined with an explicit samples value; maximum is 60.                                     |
+
 ## Scene editing
 
 ### `keyshot_import_model`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local MCP server for KeyShot product visualization, scene editing, camera control, and rendering.",
   "type": "module",
@@ -32,9 +32,15 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "ai-agent",
     "keyshot",
+    "keyshot-mcp",
     "rendering",
+    "3d-rendering",
+    "product-rendering",
+    "headless-rendering",
     "keyshot-studio",
+    "industrial-design",
     "product-visualization",
     "camera-control",
     "stdio"

package/server.json

@@ -9,12 +9,12 @@
     "url": "https://github.com/truman-t3/keyshot-mcp",
     "source": "github"
   },
-  "version": "0.10.0",
+  "version": "0.11.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "keyshot-mcp",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "transport": {
         "type": "stdio"
       },

package/skills/keyshot-mcp/SKILL.md

@@ -2,7 +2,7 @@
 name: keyshot-mcp
 author: truman-t3
 description: Install, diagnose, and safely use KeyShot MCP for local product visualization, scene editing, camera control, material assignment, and rendering.
-version: 0.10.0
+version: 0.11.0
 ---
 
 # KeyShot MCP
@@ -20,13 +20,22 @@ Respond in the user's language and explain errors in plain, non-technical terms.
 - Do not overwrite an explicit output path unless the user clearly requests it.
 - Use scene copies for editing workflows; do not modify customer source files in place.
 - Do not execute arbitrary Python or simulate KeyShot GUI actions.
+- When the user asks to control the current KeyShot window, selected GUI object,
+  or unsaved scene in realtime, explain the GUI boundary before requesting a file:
+  the stable server uses KeyShot headless on saved scenes. A persistent GUI bridge
+  was prototyped, but KeyShot Script Runner remains active for the lifetime of the
+  script and blocks normal GUI interaction. The public scripting API does not
+  provide a documented non-blocking GUI service or main-thread callback for safely
+  hosting that bridge. Do not describe this as a missing MCP feature.
+- After explaining the boundary, ask the user to save the scene and offer to edit
+  a safe copy, return an Agent-visible preview, and preserve the source file.
 
 ## Installation workflow
 
 1. Confirm Node.js 20 or newer is available.
 2. Confirm KeyShot is installed and locally licensed.
 3. Locate `keyshot_headless.exe`. Prefer its absolute path.
-4. Configure the MCP client to run `npx -y keyshot-mcp@0.10.0` and set
+4. Configure the MCP client to run `npx -y keyshot-mcp@0.11.0` and set
    `KEYSHOT_HEADLESS_EXE`.
 5. Leave `KEYSHOT_OUTPUT_DIR` unset to use
    `<home>/Documents/KeyShot MCP Outputs`, or set a user-approved directory.
@@ -41,7 +50,7 @@ Example configuration:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.10.0"],
+      "args": ["-y", "keyshot-mcp@0.11.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -58,6 +67,9 @@ Example configuration:
 - Use `keyshot_list_cameras` before rendering selected cameras.
 - Use `keyshot_preview_render` after inspection so the Agent and user can review
   composition, materials, and lighting before a standard or final render.
+- When the user has just saved a GUI scene or asks for the newest saved work, use
+  `keyshot_sync_saved_scene`. Reuse its returned fingerprint on the next check so
+  unchanged saves do not produce duplicate copies or previews.
 - Use `keyshot_render` for one view, `keyshot_batch_render` for selected views,
   `keyshot_render_all_cameras` for every saved view, and `keyshot_render_queue`
   for independent jobs from multiple scenes.
@@ -104,3 +116,9 @@ KeyShot MCP uses KeyShot headless scripting. It does not include KeyShot, a
 license, proprietary materials, environments, or customer assets. Features that
 are not exposed by the installed KeyShot headless API must be reported as
 unsupported rather than silently ignored.
+
+The stable tools do not attach to an open, unsaved KeyShot GUI session. If the
+user expects realtime control, state this before running tools and attribute the
+limitation accurately to the currently documented KeyShot GUI scripting execution
+model. Do not imply that installing or configuring the MCP differently will enable
+realtime GUI control.