keyshot-mcp 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+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
+
+- `keyshot_preview_render`, which embeds a bounded PNG preview in the MCP response.
+- A generated 18-tool reference at `docs/TOOLS.md`.
+- Documentation drift, formatting, Python lint, and release-integrity checks.
+
+### Changed
+
+- Tool metadata now comes from a shared catalog used by the server, tests, and documentation.
+- The recommended workflow now includes an Agent-visible preview and user confirmation before standard or final rendering.
+- Release automation pins MCP Publisher v1.7.9 and reports Registry failures without undoing a successful npm publication.
+
+### Security
+
+- 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.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,39 +1,86 @@
-# 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. Models, scenes, licenses, and renders stay local.
+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.9.1 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.9.1
+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.
 5. Restart or reload the MCP client and run keyshot_status.
 6. Explain any problem and its suggested fix in plain language.
-7. Do not upload or publish my KeyShot files, renders, or license information.
+7. Do not upload or publish my KeyShot files, persistent renders, or license information.
+8. Before sending a preview image to the configured model provider, remind me when the scene is confidential.
 ```
 
 After setup, try:
@@ -52,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.9.1`.
+The current release is `0.11.0`.
 
 #### Run with npx
 
@@ -65,7 +144,7 @@ No global npm installation is required:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.9.1"],
+      "args": ["-y", "keyshot-mcp@0.11.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -77,7 +156,7 @@ No global npm installation is required:
 #### Install globally
 
 ```bash
-npm install -g keyshot-mcp@0.9.1
+npm install -g keyshot-mcp@0.11.0
 ```
 
 ```json
@@ -111,6 +190,16 @@ output access, bridge files, preset JSON, and a minimal KeyShot startup.
 
 ### Common workflows
 
+#### Preview before final rendering
+
+Use `keyshot_preview_render` after checking a scene. It returns a PNG directly to
+the Agent, so composition, materials, and lighting can be described and confirmed
+before a standard or final render. Temporary previews are deleted automatically;
+set `outputPath` only when a persistent PNG copy is needed.
+
+Recommended loop: status check -> scene inspection -> preview -> Agent feedback ->
+user confirmation -> standard or final render.
+
 #### One-call product render
 
 `keyshot_product_render` is the recommended high-level tool for ordinary product
@@ -155,11 +244,11 @@ different KeyShot render modes and cannot be combined.
 
 ### Quality presets
 
-| Preset | Resolution | Samples | Use |
-| --- | ---: | ---: | --- |
-| `preview` | 960 x 540 | 16 | Fast composition and material checks |
-| `standard` | 1920 x 1080 | 64 | Default for `keyshot_product_render` |
-| `final` | 3840 x 2160 | 256 | High-resolution final output |
+| Preset     |  Resolution | Samples | Use                                  |
+| ---------- | ----------: | ------: | ------------------------------------ |
+| `preview`  |   960 x 540 |      16 | Fast composition and material checks |
+| `standard` | 1920 x 1080 |      64 | Default for `keyshot_product_render` |
+| `final`    | 3840 x 2160 |     256 | High-resolution final output         |
 
 Explicit `width`, `height`, and `samples` override the corresponding preset values.
 Explicit `maxTimeSeconds` switches to time-based rendering instead of preset samples.
@@ -167,42 +256,45 @@ Lower-level render tools preserve their existing behavior when no preset is give
 
 ### Tools
 
-| Tool | Purpose |
-| --- | --- |
-| `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_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. |
-| `keyshot_render_queue` | Run independent render jobs sequentially. |
-| `keyshot_batch_render` | Render selected named cameras from one scene. |
-| `keyshot_render_all_cameras` | Discover and render every saved camera. |
-| `keyshot_import_model` | Import a model into an empty or base scene and save it. |
-| `keyshot_apply_material` | Apply a KeyShot material name or local material file to one object. |
-| `keyshot_list_material_presets` | List configured material presets. |
-| `keyshot_apply_material_preset` | Apply a configured material preset to one object. |
-| `keyshot_set_camera` | Create or update camera transform, distance, FOV, or focal length. |
-| `keyshot_list_camera_presets` | List standard and custom camera presets. |
-| `keyshot_apply_camera_preset` | Create or update a camera from a preset. |
-| `keyshot_set_environment` | Select or adjust an environment, brightness, and rotation. |
-| `keyshot_save_scene` | Save an existing scene to a controlled output path. |
+| Tool                            | Purpose                                                                       |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `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.                                            |
+| `keyshot_render_queue`          | Run independent render jobs sequentially.                                     |
+| `keyshot_batch_render`          | Render selected named cameras from one scene.                                 |
+| `keyshot_render_all_cameras`    | Discover and render every saved camera.                                       |
+| `keyshot_import_model`          | Import a model into an empty or base scene and save it.                       |
+| `keyshot_apply_material`        | Apply a KeyShot material name or local material file to one object.           |
+| `keyshot_list_material_presets` | List configured material presets.                                             |
+| `keyshot_apply_material_preset` | Apply a configured material preset to one object.                             |
+| `keyshot_set_camera`            | Create or update camera transform, distance, FOV, or focal length.            |
+| `keyshot_list_camera_presets`   | List standard and custom camera presets.                                      |
+| `keyshot_apply_camera_preset`   | Create or update a camera from a preset.                                      |
+| `keyshot_set_environment`       | Select or adjust an environment, brightness, and rotation.                    |
+| `keyshot_save_scene`            | Save an existing scene to a controlled output path.                           |
 
 The server also exposes one MCP Prompt for product rendering and one MCP Resource
-describing the KeyShot headless workflow. The bundled Agent Skill in
+describing the KeyShot headless workflow. The complete generated reference for
+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.
 
 ### Configuration
 
-| Variable | Default | Description |
-| --- | --- | --- |
-| `KEYSHOT_HEADLESS_EXE` | `D:\keyshot2025_183972\bin\keyshot_headless.exe` | Full executable path or a command available on `PATH`. |
-| `KEYSHOT_OUTPUT_DIR` | `<home>/Documents/KeyShot MCP Outputs` | Root for rendered images and saved scenes. |
-| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | Allow output outside the configured root only when explicitly set to `true`. |
-| `KEYSHOT_TIMEOUT_MS` | `600000` | Timeout for one KeyShot process. |
-| `KEYSHOT_LICENSE_ARGS` | empty | Optional launch arguments; diagnostics never echo their values. |
-| `KEYSHOT_MATERIAL_PRESETS` | bundled JSON | Optional user-managed material preset file. |
-| `KEYSHOT_CAMERA_PRESETS` | bundled JSON | Optional user-managed camera preset file. |
+| Variable                         | Default                                | Description                                                                  |
+| -------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `KEYSHOT_HEADLESS_EXE`           | `keyshot_headless.exe` on Windows      | Full executable path or a command available on `PATH`.                       |
+| `KEYSHOT_OUTPUT_DIR`             | `<home>/Documents/KeyShot MCP Outputs` | Root for rendered images and saved scenes.                                   |
+| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false`                                | Allow output outside the configured root only when explicitly set to `true`. |
+| `KEYSHOT_TIMEOUT_MS`             | `600000`                               | Timeout for one KeyShot process.                                             |
+| `KEYSHOT_LICENSE_ARGS`           | empty                                  | Optional launch arguments; diagnostics never echo their values.              |
+| `KEYSHOT_MATERIAL_PRESETS`       | bundled JSON                           | Optional user-managed material preset file.                                  |
+| `KEYSHOT_CAMERA_PRESETS`         | bundled JSON                           | Optional user-managed camera preset file.                                    |
 
 All KeyShot operations run sequentially to reduce license and output conflicts.
 Input scenes and models may come from any local path. By default, generated images
@@ -275,20 +367,39 @@ 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.9.1，并配置到我的 MCP 客户端。
+请安装 KeyShot MCP 0.11.0，并配置到我的 MCP 客户端。
 
-1. 使用：npx -y keyshot-mcp@0.9.1
+1. 使用：npx -y keyshot-mcp@0.11.0
 2. 查找本机 keyshot_headless.exe，并把完整路径设置为 KEYSHOT_HEADLESS_EXE。
 3. 默认把结果保存在“文档/KeyShot MCP Outputs”，除非我明确选择其他安全目录。
 4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
 5. 重启或重新加载 MCP 客户端，然后运行 keyshot_status。
 6. 用普通设计师能理解的语言说明问题和修复建议。
-7. 不要上传或发布我的 KeyShot 文件、渲染图或许可证信息。
+7. 不要上传或发布我的 KeyShot 文件、保留的渲染图或许可证信息。
+8. 如果场景属于保密项目，在把预览发送给模型服务之前先提醒我。
 ```
 
 安装后可以这样说：
@@ -305,9 +416,36 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
 - 暴露相同脚本 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.9.1`。
+当前正式版本为 `0.11.0`。
 
 #### 使用 npx 免安装运行
 
@@ -316,7 +454,7 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.9.1"],
+      "args": ["-y", "keyshot-mcp@0.11.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -328,7 +466,7 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
 #### 全局安装
 
 ```bash
-npm install -g keyshot-mcp@0.9.1
+npm install -g keyshot-mcp@0.11.0
 ```
 
 ```json
@@ -361,6 +499,15 @@ pnpm build
 
 ### 常用工作流
 
+#### 正式渲染前先看预览
+
+检查场景后调用 `keyshot_preview_render`。它会把 PNG 直接返回给 Agent，便于
+先检查构图、材质和光线，再由用户确认是否继续标准或最终渲染。临时预览会自动
+删除；只有需要保留图片时才填写 `outputPath`。
+
+推荐流程：状态检查 -> 场景检查 -> 预览 -> Agent 描述问题 -> 用户确认 ->
+标准或最终渲染。
+
 #### 一句话完成产品出图
 
 普通产品工作优先使用 `keyshot_product_render`。它能在一个 KeyShot 进程中导入模型
@@ -402,52 +549,55 @@ pnpm build
 
 ### 质量预设
 
-| 预设 | 分辨率 | 采样 | 用途 |
-| --- | ---: | ---: | --- |
-| `preview` | 960 x 540 | 16 | 快速检查构图和材质 |
-| `standard` | 1920 x 1080 | 64 | `keyshot_product_render` 的默认值 |
-| `final` | 3840 x 2160 | 256 | 高清最终输出 |
+| 预设       |      分辨率 | 采样 | 用途                              |
+| ---------- | ----------: | ---: | --------------------------------- |
+| `preview`  |   960 x 540 |   16 | 快速检查构图和材质                |
+| `standard` | 1920 x 1080 |   64 | `keyshot_product_render` 的默认值 |
+| `final`    | 3840 x 2160 |  256 | 高清最终输出                      |
 
 显式填写的 `width`、`height` 和 `samples` 会分别覆盖预设值；填写
 `maxTimeSeconds` 会改用限时渲染。底层渲染工具在没有指定预设时保持原有行为。
 
 ### 工具
 
-| 工具 | 用途 |
-| --- | --- |
-| `keyshot_status` | 检查本机配置、输出目录、预设和 KeyShot 启动状态。 |
-| `keyshot_product_render` | 在一个进程中整理、保存并渲染模型或场景。 |
-| `keyshot_inspect_scene` | 查看场景、对象、相机、材质、模型集和外部引用。 |
-| `keyshot_list_cameras` | 返回场景中的相机名称。 |
-| `keyshot_render` | 渲染当前或指定相机。 |
-| `keyshot_render_queue` | 顺序执行多个独立渲染任务。 |
-| `keyshot_batch_render` | 渲染选定的多个相机。 |
-| `keyshot_render_all_cameras` | 自动发现并渲染全部相机。 |
-| `keyshot_import_model` | 导入模型并保存为场景。 |
-| `keyshot_apply_material` | 给指定对象应用材质名称或本地材质文件。 |
-| `keyshot_list_material_presets` | 列出材质预设。 |
-| `keyshot_apply_material_preset` | 给指定对象应用材质预设。 |
-| `keyshot_set_camera` | 创建或修改相机位置、距离、视野角或焦距。 |
-| `keyshot_list_camera_presets` | 列出标准与自定义相机预设。 |
-| `keyshot_apply_camera_preset` | 根据预设创建或修改相机。 |
-| `keyshot_set_environment` | 选择或调整环境、亮度和旋转。 |
-| `keyshot_save_scene` | 将场景保存到受控输出路径。 |
+| 工具                            | 用途                                               |
+| ------------------------------- | -------------------------------------------------- |
+| `keyshot_status`                | 检查本机配置、输出目录、预设和 KeyShot 启动状态。  |
+| `keyshot_product_render`        | 在一个进程中整理、保存并渲染模型或场景。           |
+| `keyshot_preview_render`        | 将临时或保留的 PNG 直接返回给 Agent 进行视觉检查。 |
+| `keyshot_sync_saved_scene`      | 安全同步最近保存的场景、检测变化并返回预览。       |
+| `keyshot_inspect_scene`         | 查看场景、对象、相机、材质、模型集和外部引用。     |
+| `keyshot_list_cameras`          | 返回场景中的相机名称。                             |
+| `keyshot_render`                | 渲染当前或指定相机。                               |
+| `keyshot_render_queue`          | 顺序执行多个独立渲染任务。                         |
+| `keyshot_batch_render`          | 渲染选定的多个相机。                               |
+| `keyshot_render_all_cameras`    | 自动发现并渲染全部相机。                           |
+| `keyshot_import_model`          | 导入模型并保存为场景。                             |
+| `keyshot_apply_material`        | 给指定对象应用材质名称或本地材质文件。             |
+| `keyshot_list_material_presets` | 列出材质预设。                                     |
+| `keyshot_apply_material_preset` | 给指定对象应用材质预设。                           |
+| `keyshot_set_camera`            | 创建或修改相机位置、距离、视野角或焦距。           |
+| `keyshot_list_camera_presets`   | 列出标准与自定义相机预设。                         |
+| `keyshot_apply_camera_preset`   | 根据预设创建或修改相机。                           |
+| `keyshot_set_environment`       | 选择或调整环境、亮度和旋转。                       |
+| `keyshot_save_scene`            | 将场景保存到受控输出路径。                         |
 
 服务还提供一个产品渲染 MCP Prompt，以及一个说明 headless 工作流程的 MCP Resource。
+完整的 19 个工具参考由代码自动生成在 [`docs/TOOLS.md`](docs/TOOLS.md)。
 [`skills/keyshot-mcp`](skills/keyshot-mcp) 中的 Agent Skill 会指导兼容的 Agent 安装、
 诊断并安全使用这些工具。
 
 ### 配置
 
-| 环境变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `KEYSHOT_HEADLESS_EXE` | `D:\keyshot2025_183972\bin\keyshot_headless.exe` | 完整路径，或系统 `PATH` 中可执行的命令。 |
-| `KEYSHOT_OUTPUT_DIR` | `<用户目录>/Documents/KeyShot MCP Outputs` | 渲染图和场景副本的根目录。 |
-| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | 只有明确设为 `true` 时才允许写到输出根目录之外。 |
-| `KEYSHOT_TIMEOUT_MS` | `600000` | 单次 KeyShot 进程超时时间。 |
-| `KEYSHOT_LICENSE_ARGS` | 空 | 可选启动参数；诊断结果不会回显具体内容。 |
-| `KEYSHOT_MATERIAL_PRESETS` | 内置 JSON | 可选的用户材质预设文件。 |
-| `KEYSHOT_CAMERA_PRESETS` | 内置 JSON | 可选的用户相机预设文件。 |
+| 环境变量                         | 默认值                                     | 说明                                             |
+| -------------------------------- | ------------------------------------------ | ------------------------------------------------ |
+| `KEYSHOT_HEADLESS_EXE`           | Windows 上为 `keyshot_headless.exe`        | 完整路径，或系统 `PATH` 中可执行的命令。         |
+| `KEYSHOT_OUTPUT_DIR`             | `<用户目录>/Documents/KeyShot MCP Outputs` | 渲染图和场景副本的根目录。                       |
+| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false`                                    | 只有明确设为 `true` 时才允许写到输出根目录之外。 |
+| `KEYSHOT_TIMEOUT_MS`             | `600000`                                   | 单次 KeyShot 进程超时时间。                      |
+| `KEYSHOT_LICENSE_ARGS`           | 空                                         | 可选启动参数；诊断结果不会回显具体内容。         |
+| `KEYSHOT_MATERIAL_PRESETS`       | 内置 JSON                                  | 可选的用户材质预设文件。                         |
+| `KEYSHOT_CAMERA_PRESETS`         | 内置 JSON                                  | 可选的用户相机预设文件。                         |
 
 所有 KeyShot 操作串行执行，减少许可证和文件冲突。输入模型和场景可以位于任意本地
 路径；生成的场景和图片默认只能写入 `KEYSHOT_OUTPUT_DIR`。系统会拒绝 `..`、同名前缀

package/SECURITY.md

@@ -2,32 +2,62 @@
 
 ## English
 
-This MCP server runs KeyShot headless on the local machine. It can read scene/model files and write rendered images or saved scenes.
+KeyShot MCP runs KeyShot headless on the local computer. It can read local scene,
+model, material, and environment files and can write rendered images or scene copies.
 
-### Safe Use
+### Model-provider data flow
 
-- Only connect this server to MCP clients you trust.
-- Only open scene/model/material files from trusted sources.
-- Do not put license keys, account passwords, or private tokens in prompts.
-- Prefer using the local KeyShot license configuration instead of passing license details through environment variables.
+MCP clients normally send tool inputs and results to the model service selected by
+the user. Scene metadata returned by inspection tools and images returned by
+`keyshot_preview_render` may therefore leave the local computer through that MCP
+client. Review the client and model provider's privacy settings before using private
+or customer work.
 
-### Reporting Issues
+KeyShot MCP itself does not upload files, run a remote service, or collect telemetry.
+It never requires license keys in prompts and does not expose arbitrary Python
+execution.
 
-If you find a security issue, open a private advisory or contact the project maintainer directly before posting details publicly.
+### Safe use
+
+- Connect the server only to MCP clients and model providers you trust.
+- Open only scene, model, material, and environment files from trusted sources.
+- Do not put license keys, account passwords, private tokens, or confidential asset
+  contents in prompts.
+- Use KeyShot's existing local license configuration.
+- Keep `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` disabled unless an external destination is
+  explicitly required and trusted.
+- Review a preview before approving edits or final renders, and preserve source scenes.
+
+### Reporting issues
+
+Report vulnerabilities through a private GitHub security advisory before posting
+technical details publicly.
 
 ---
 
 ## 中文
 
-这个 MCP 服务会在本机运行 KeyShot 无界面程序。它可以读取场景、模型、材质文件，也可以写入渲染图片或保存后的场景文件。
+KeyShot MCP 在本机运行 KeyShot headless。它可以读取本地场景、模型、材质和环境
+文件，也可以写入渲染图片或场景副本。
+
+### 模型服务的数据流
+
+MCP 客户端通常会把工具输入和结果发送给用户选择的模型服务。因此，场景检查工具
+返回的元数据，以及 `keyshot_preview_render` 返回的预览图片，可能通过 MCP 客户端
+离开本机。处理私有项目或客户项目之前，请先确认 MCP 客户端和模型服务商的隐私设置。
+
+KeyShot MCP 本身不会上传文件、运行远程服务或收集遥测数据。它不会要求用户在提示词
+中提供许可证密钥，也不开放任意 Python 执行。
 
-### 安全使用建议
+### 安全使用
 
-- 只把这个服务连接到你信任的 MCP 客户端。
-- 只打开来源可信的场景、模型和材质文件。
-- 不要在提示词里输入许可证密钥、账号密码或私人 token。
-- 优先使用本机已经配置好的 KeyShot 授权，不建议通过环境变量传递许可证细节。
+- 只连接可信的 MCP 客户端和模型服务。
+- 只打开来源可信的场景、模型、材质和环境文件。
+- 不要在提示词中填写许可证密钥、账号密码、私有 Token 或保密素材内容。
+- 使用 KeyShot 已有的本机许可证配置。
+- 除非明确需要并信任外部位置，否则保持 `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` 关闭。
+- 批准修改或最终渲染前先检查预览，并保留原始场景。
 
 ### 报告安全问题
 
-如果发现安全问题，请先通过私密方式联系维护者，不要直接公开细节。
+请先通过 GitHub 私密安全公告报告漏洞，不要直接公开技术细节。

package/dist/config.js

@@ -15,8 +15,10 @@ export function getConfig() {
         keyshotTimeoutMs: parsePositiveInt(process.env.KEYSHOT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
         tmpDir: path.join(projectRoot, "work", "tmp"),
         bridgeScriptPath: path.join(projectRoot, "scripts", "keyshot_bridge.py"),
-        materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ?? path.join(projectRoot, "presets", "materials.json")),
-        cameraPresetsPath: path.resolve(process.env.KEYSHOT_CAMERA_PRESETS ?? path.join(projectRoot, "presets", "cameras.json")),
+        materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ??
+            path.join(projectRoot, "presets", "materials.json")),
+        cameraPresetsPath: path.resolve(process.env.KEYSHOT_CAMERA_PRESETS ??
+            path.join(projectRoot, "presets", "cameras.json")),
     };
 }
 export function defaultOutputDir() {