keyshot-mcp 0.9.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +110 -80
  3. package/SECURITY.md +45 -15
  4. package/dist/config.js +4 -2
  5. package/dist/diagnostics.js +25 -9
  6. package/dist/index.js +3 -317
  7. package/dist/output-collisions.js +8 -2
  8. package/dist/output-paths.js +4 -1
  9. package/dist/preview.js +138 -0
  10. package/dist/product-render.js +6 -2
  11. package/dist/result.js +78 -19
  12. package/dist/runner.js +17 -7
  13. package/dist/schemas.js +408 -82
  14. package/dist/server.js +252 -0
  15. package/dist/tools/catalog.js +210 -0
  16. package/dist/version.js +1 -1
  17. package/docs/TOOLS.md +323 -0
  18. package/glama.json +1 -3
  19. package/package.json +9 -1
  20. package/scripts/clean.mjs +4 -1
  21. package/scripts/keyshot-smoke.mjs +130 -53
  22. package/server.json +2 -2
  23. package/skills/keyshot-mcp/SKILL.md +14 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,26 @@
1
+ # Changelog
2
+
3
+ All notable changes to KeyShot MCP are documented in this file.
4
+
5
+ ## [Unreleased]
6
+
7
+ ## [0.10.0] - 2026-08-11
8
+
9
+ ### Added
10
+
11
+ - `keyshot_preview_render`, which embeds a bounded PNG preview in the MCP response.
12
+ - A generated 18-tool reference at `docs/TOOLS.md`.
13
+ - Documentation drift, formatting, Python lint, and release-integrity checks.
14
+
15
+ ### Changed
16
+
17
+ - Tool metadata now comes from a shared catalog used by the server, tests, and documentation.
18
+ - The recommended workflow now includes an Agent-visible preview and user confirmation before standard or final rendering.
19
+ - Release automation pins MCP Publisher v1.7.9 and reports Registry failures without undoing a successful npm publication.
20
+
21
+ ### Security
22
+
23
+ - Documented that scene metadata and preview images may be sent by an MCP client to its configured model provider.
24
+
25
+ [Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.10.0...HEAD
26
+ [0.10.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.9.1...v0.10.0
package/README.md CHANGED
@@ -13,7 +13,9 @@
13
13
  KeyShot MCP connects an MCP-compatible AI agent to a licensed KeyShot installation
14
14
  on the same computer. It can inspect scenes, import models, apply materials, set
15
15
  cameras and environments, save scene copies, and render images through KeyShot
16
- headless scripting. Models, scenes, licenses, and renders stay local.
16
+ headless scripting. KeyShot file processing stays local; however, an MCP client may
17
+ send tool results, scene metadata, or embedded previews to its configured model
18
+ provider. See [Security](SECURITY.md) before using confidential work.
17
19
 
18
20
  ![KeyShot MCP workflow](assets/workflow.svg)
19
21
 
@@ -25,15 +27,16 @@ The easiest setup is to send this prompt to an agent that can edit your MCP
25
27
  configuration:
26
28
 
27
29
  ```text
28
- Install KeyShot MCP 0.9.1 and configure it in my MCP client.
30
+ Install KeyShot MCP 0.10.0 and configure it in my MCP client.
29
31
 
30
- 1. Use: npx -y keyshot-mcp@0.9.1
32
+ 1. Use: npx -y keyshot-mcp@0.10.0
31
33
  2. Find my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE to its full path.
32
34
  3. Keep outputs in the default KeyShot MCP Outputs folder unless I choose another safe folder.
33
35
  4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
34
36
  5. Restart or reload the MCP client and run keyshot_status.
35
37
  6. Explain any problem and its suggested fix in plain language.
36
- 7. Do not upload or publish my KeyShot files, renders, or license information.
38
+ 7. Do not upload or publish my KeyShot files, persistent renders, or license information.
39
+ 8. Before sending a preview image to the configured model provider, remind me when the scene is confidential.
37
40
  ```
38
41
 
39
42
  After setup, try:
@@ -54,7 +57,7 @@ from C:\models\speaker.obj.
54
57
 
55
58
  ### Install
56
59
 
57
- The current release is `0.9.1`.
60
+ The current release is `0.10.0`.
58
61
 
59
62
  #### Run with npx
60
63
 
@@ -65,7 +68,7 @@ No global npm installation is required:
65
68
  "mcpServers": {
66
69
  "keyshot": {
67
70
  "command": "npx",
68
- "args": ["-y", "keyshot-mcp@0.9.1"],
71
+ "args": ["-y", "keyshot-mcp@0.10.0"],
69
72
  "env": {
70
73
  "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
71
74
  }
@@ -77,7 +80,7 @@ No global npm installation is required:
77
80
  #### Install globally
78
81
 
79
82
  ```bash
80
- npm install -g keyshot-mcp@0.9.1
83
+ npm install -g keyshot-mcp@0.10.0
81
84
  ```
82
85
 
83
86
  ```json
@@ -111,6 +114,16 @@ output access, bridge files, preset JSON, and a minimal KeyShot startup.
111
114
 
112
115
  ### Common workflows
113
116
 
117
+ #### Preview before final rendering
118
+
119
+ Use `keyshot_preview_render` after checking a scene. It returns a PNG directly to
120
+ the Agent, so composition, materials, and lighting can be described and confirmed
121
+ before a standard or final render. Temporary previews are deleted automatically;
122
+ set `outputPath` only when a persistent PNG copy is needed.
123
+
124
+ Recommended loop: status check -> scene inspection -> preview -> Agent feedback ->
125
+ user confirmation -> standard or final render.
126
+
114
127
  #### One-call product render
115
128
 
116
129
  `keyshot_product_render` is the recommended high-level tool for ordinary product
@@ -155,11 +168,11 @@ different KeyShot render modes and cannot be combined.
155
168
 
156
169
  ### Quality presets
157
170
 
158
- | Preset | Resolution | Samples | Use |
159
- | --- | ---: | ---: | --- |
160
- | `preview` | 960 x 540 | 16 | Fast composition and material checks |
161
- | `standard` | 1920 x 1080 | 64 | Default for `keyshot_product_render` |
162
- | `final` | 3840 x 2160 | 256 | High-resolution final output |
171
+ | Preset | Resolution | Samples | Use |
172
+ | ---------- | ----------: | ------: | ------------------------------------ |
173
+ | `preview` | 960 x 540 | 16 | Fast composition and material checks |
174
+ | `standard` | 1920 x 1080 | 64 | Default for `keyshot_product_render` |
175
+ | `final` | 3840 x 2160 | 256 | High-resolution final output |
163
176
 
164
177
  Explicit `width`, `height`, and `samples` override the corresponding preset values.
165
178
  Explicit `maxTimeSeconds` switches to time-based rendering instead of preset samples.
@@ -167,42 +180,44 @@ Lower-level render tools preserve their existing behavior when no preset is give
167
180
 
168
181
  ### Tools
169
182
 
170
- | Tool | Purpose |
171
- | --- | --- |
172
- | `keyshot_status` | Diagnose local configuration, output access, presets, and KeyShot startup. |
173
- | `keyshot_product_render` | Prepare, save, and render a model or scene in one process. |
174
- | `keyshot_inspect_scene` | List scene metadata, objects, cameras, materials, model sets, and references. |
175
- | `keyshot_list_cameras` | Return saved camera names before a selected-camera render. |
176
- | `keyshot_render` | Render one active or named camera. |
177
- | `keyshot_render_queue` | Run independent render jobs sequentially. |
178
- | `keyshot_batch_render` | Render selected named cameras from one scene. |
179
- | `keyshot_render_all_cameras` | Discover and render every saved camera. |
180
- | `keyshot_import_model` | Import a model into an empty or base scene and save it. |
181
- | `keyshot_apply_material` | Apply a KeyShot material name or local material file to one object. |
182
- | `keyshot_list_material_presets` | List configured material presets. |
183
- | `keyshot_apply_material_preset` | Apply a configured material preset to one object. |
184
- | `keyshot_set_camera` | Create or update camera transform, distance, FOV, or focal length. |
185
- | `keyshot_list_camera_presets` | List standard and custom camera presets. |
186
- | `keyshot_apply_camera_preset` | Create or update a camera from a preset. |
187
- | `keyshot_set_environment` | Select or adjust an environment, brightness, and rotation. |
188
- | `keyshot_save_scene` | Save an existing scene to a controlled output path. |
183
+ | Tool | Purpose |
184
+ | ------------------------------- | ----------------------------------------------------------------------------- |
185
+ | `keyshot_status` | Diagnose local configuration, output access, presets, and KeyShot startup. |
186
+ | `keyshot_product_render` | Prepare, save, and render a model or scene in one process. |
187
+ | `keyshot_preview_render` | Return a temporary or saved PNG directly to the Agent for visual review. |
188
+ | `keyshot_inspect_scene` | List scene metadata, objects, cameras, materials, model sets, and references. |
189
+ | `keyshot_list_cameras` | Return saved camera names before a selected-camera render. |
190
+ | `keyshot_render` | Render one active or named camera. |
191
+ | `keyshot_render_queue` | Run independent render jobs sequentially. |
192
+ | `keyshot_batch_render` | Render selected named cameras from one scene. |
193
+ | `keyshot_render_all_cameras` | Discover and render every saved camera. |
194
+ | `keyshot_import_model` | Import a model into an empty or base scene and save it. |
195
+ | `keyshot_apply_material` | Apply a KeyShot material name or local material file to one object. |
196
+ | `keyshot_list_material_presets` | List configured material presets. |
197
+ | `keyshot_apply_material_preset` | Apply a configured material preset to one object. |
198
+ | `keyshot_set_camera` | Create or update camera transform, distance, FOV, or focal length. |
199
+ | `keyshot_list_camera_presets` | List standard and custom camera presets. |
200
+ | `keyshot_apply_camera_preset` | Create or update a camera from a preset. |
201
+ | `keyshot_set_environment` | Select or adjust an environment, brightness, and rotation. |
202
+ | `keyshot_save_scene` | Save an existing scene to a controlled output path. |
189
203
 
190
204
  The server also exposes one MCP Prompt for product rendering and one MCP Resource
191
- describing the KeyShot headless workflow. The bundled Agent Skill in
205
+ describing the KeyShot headless workflow. The complete generated reference for
206
+ all 18 tools is in [`docs/TOOLS.md`](docs/TOOLS.md). The bundled Agent Skill in
192
207
  [`skills/keyshot-mcp`](skills/keyshot-mcp) teaches compatible agents how to install,
193
208
  diagnose, and use the server safely.
194
209
 
195
210
  ### Configuration
196
211
 
197
- | Variable | Default | Description |
198
- | --- | --- | --- |
199
- | `KEYSHOT_HEADLESS_EXE` | `D:\keyshot2025_183972\bin\keyshot_headless.exe` | Full executable path or a command available on `PATH`. |
200
- | `KEYSHOT_OUTPUT_DIR` | `<home>/Documents/KeyShot MCP Outputs` | Root for rendered images and saved scenes. |
201
- | `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | Allow output outside the configured root only when explicitly set to `true`. |
202
- | `KEYSHOT_TIMEOUT_MS` | `600000` | Timeout for one KeyShot process. |
203
- | `KEYSHOT_LICENSE_ARGS` | empty | Optional launch arguments; diagnostics never echo their values. |
204
- | `KEYSHOT_MATERIAL_PRESETS` | bundled JSON | Optional user-managed material preset file. |
205
- | `KEYSHOT_CAMERA_PRESETS` | bundled JSON | Optional user-managed camera preset file. |
212
+ | Variable | Default | Description |
213
+ | -------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
214
+ | `KEYSHOT_HEADLESS_EXE` | `keyshot_headless.exe` on Windows | Full executable path or a command available on `PATH`. |
215
+ | `KEYSHOT_OUTPUT_DIR` | `<home>/Documents/KeyShot MCP Outputs` | Root for rendered images and saved scenes. |
216
+ | `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | Allow output outside the configured root only when explicitly set to `true`. |
217
+ | `KEYSHOT_TIMEOUT_MS` | `600000` | Timeout for one KeyShot process. |
218
+ | `KEYSHOT_LICENSE_ARGS` | empty | Optional launch arguments; diagnostics never echo their values. |
219
+ | `KEYSHOT_MATERIAL_PRESETS` | bundled JSON | Optional user-managed material preset file. |
220
+ | `KEYSHOT_CAMERA_PRESETS` | bundled JSON | Optional user-managed camera preset file. |
206
221
 
207
222
  All KeyShot operations run sequentially to reduce license and output conflicts.
208
223
  Input scenes and models may come from any local path. By default, generated images
@@ -275,20 +290,24 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
275
290
 
276
291
  ## 中文
277
292
 
293
+ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具结果、场景元数据或
294
+ 内嵌预览发送给它所配置的模型服务。处理保密项目之前请先阅读[安全说明](SECURITY.md)。
295
+
278
296
  ### 设计师快速开始
279
297
 
280
298
  最简单的安装方式，是把下面这段话发给能够修改 MCP 配置的 Agent：
281
299
 
282
300
  ```text
283
- 请安装 KeyShot MCP 0.9.1，并配置到我的 MCP 客户端。
301
+ 请安装 KeyShot MCP 0.10.0，并配置到我的 MCP 客户端。
284
302
 
285
- 1. 使用：npx -y keyshot-mcp@0.9.1
303
+ 1. 使用：npx -y keyshot-mcp@0.10.0
286
304
  2. 查找本机 keyshot_headless.exe，并把完整路径设置为 KEYSHOT_HEADLESS_EXE。
287
305
  3. 默认把结果保存在“文档/KeyShot MCP Outputs”，除非我明确选择其他安全目录。
288
306
  4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
289
307
  5. 重启或重新加载 MCP 客户端，然后运行 keyshot_status。
290
308
  6. 用普通设计师能理解的语言说明问题和修复建议。
291
- 7. 不要上传或发布我的 KeyShot 文件、渲染图或许可证信息。
309
+ 7. 不要上传或发布我的 KeyShot 文件、保留的渲染图或许可证信息。
310
+ 8. 如果场景属于保密项目，在把预览发送给模型服务之前先提醒我。
292
311
  ```
293
312
 
294
313
  安装后可以这样说：
@@ -307,7 +326,7 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
307
326
 
308
327
  ### 安装
309
328
 
310
- 当前正式版本为 `0.9.1`。
329
+ 当前正式版本为 `0.10.0`。
311
330
 
312
331
  #### 使用 npx 免安装运行
313
332
 
@@ -316,7 +335,7 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
316
335
  "mcpServers": {
317
336
  "keyshot": {
318
337
  "command": "npx",
319
- "args": ["-y", "keyshot-mcp@0.9.1"],
338
+ "args": ["-y", "keyshot-mcp@0.10.0"],
320
339
  "env": {
321
340
  "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
322
341
  }
@@ -328,7 +347,7 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
328
347
  #### 全局安装
329
348
 
330
349
  ```bash
331
- npm install -g keyshot-mcp@0.9.1
350
+ npm install -g keyshot-mcp@0.10.0
332
351
  ```
333
352
 
334
353
  ```json
@@ -361,6 +380,15 @@ pnpm build
361
380
 
362
381
  ### 常用工作流
363
382
 
383
+ #### 正式渲染前先看预览
384
+
385
+ 检查场景后调用 `keyshot_preview_render`。它会把 PNG 直接返回给 Agent，便于
386
+ 先检查构图、材质和光线，再由用户确认是否继续标准或最终渲染。临时预览会自动
387
+ 删除；只有需要保留图片时才填写 `outputPath`。
388
+
389
+ 推荐流程：状态检查 -> 场景检查 -> 预览 -> Agent 描述问题 -> 用户确认 ->
390
+ 标准或最终渲染。
391
+
364
392
  #### 一句话完成产品出图
365
393
 
366
394
  普通产品工作优先使用 `keyshot_product_render`。它能在一个 KeyShot 进程中导入模型
@@ -402,52 +430,54 @@ pnpm build
402
430
 
403
431
  ### 质量预设
404
432
 
405
- | 预设 | 分辨率 | 采样 | 用途 |
406
- | --- | ---: | ---: | --- |
407
- | `preview` | 960 x 540 | 16 | 快速检查构图和材质 |
408
- | `standard` | 1920 x 1080 | 64 | `keyshot_product_render` 的默认值 |
409
- | `final` | 3840 x 2160 | 256 | 高清最终输出 |
433
+ | 预设 | 分辨率 | 采样 | 用途 |
434
+ | ---------- | ----------: | ---: | --------------------------------- |
435
+ | `preview` | 960 x 540 | 16 | 快速检查构图和材质 |
436
+ | `standard` | 1920 x 1080 | 64 | `keyshot_product_render` 的默认值 |
437
+ | `final` | 3840 x 2160 | 256 | 高清最终输出 |
410
438
 
411
439
  显式填写的 `width`、`height` 和 `samples` 会分别覆盖预设值；填写
412
440
  `maxTimeSeconds` 会改用限时渲染。底层渲染工具在没有指定预设时保持原有行为。
413
441
 
414
442
  ### 工具
415
443
 
416
- | 工具 | 用途 |
417
- | --- | --- |
418
- | `keyshot_status` | 检查本机配置、输出目录、预设和 KeyShot 启动状态。 |
419
- | `keyshot_product_render` | 在一个进程中整理、保存并渲染模型或场景。 |
420
- | `keyshot_inspect_scene` | 查看场景、对象、相机、材质、模型集和外部引用。 |
421
- | `keyshot_list_cameras` | 返回场景中的相机名称。 |
422
- | `keyshot_render` | 渲染当前或指定相机。 |
423
- | `keyshot_render_queue` | 顺序执行多个独立渲染任务。 |
424
- | `keyshot_batch_render` | 渲染选定的多个相机。 |
425
- | `keyshot_render_all_cameras` | 自动发现并渲染全部相机。 |
426
- | `keyshot_import_model` | 导入模型并保存为场景。 |
427
- | `keyshot_apply_material` | 给指定对象应用材质名称或本地材质文件。 |
428
- | `keyshot_list_material_presets` | 列出材质预设。 |
429
- | `keyshot_apply_material_preset` | 给指定对象应用材质预设。 |
430
- | `keyshot_set_camera` | 创建或修改相机位置、距离、视野角或焦距。 |
431
- | `keyshot_list_camera_presets` | 列出标准与自定义相机预设。 |
432
- | `keyshot_apply_camera_preset` | 根据预设创建或修改相机。 |
433
- | `keyshot_set_environment` | 选择或调整环境、亮度和旋转。 |
434
- | `keyshot_save_scene` | 将场景保存到受控输出路径。 |
444
+ | 工具 | 用途 |
445
+ | ------------------------------- | -------------------------------------------------- |
446
+ | `keyshot_status` | 检查本机配置、输出目录、预设和 KeyShot 启动状态。 |
447
+ | `keyshot_product_render` | 在一个进程中整理、保存并渲染模型或场景。 |
448
+ | `keyshot_preview_render` | 将临时或保留的 PNG 直接返回给 Agent 进行视觉检查。 |
449
+ | `keyshot_inspect_scene` | 查看场景、对象、相机、材质、模型集和外部引用。 |
450
+ | `keyshot_list_cameras` | 返回场景中的相机名称。 |
451
+ | `keyshot_render` | 渲染当前或指定相机。 |
452
+ | `keyshot_render_queue` | 顺序执行多个独立渲染任务。 |
453
+ | `keyshot_batch_render` | 渲染选定的多个相机。 |
454
+ | `keyshot_render_all_cameras` | 自动发现并渲染全部相机。 |
455
+ | `keyshot_import_model` | 导入模型并保存为场景。 |
456
+ | `keyshot_apply_material` | 给指定对象应用材质名称或本地材质文件。 |
457
+ | `keyshot_list_material_presets` | 列出材质预设。 |
458
+ | `keyshot_apply_material_preset` | 给指定对象应用材质预设。 |
459
+ | `keyshot_set_camera` | 创建或修改相机位置、距离、视野角或焦距。 |
460
+ | `keyshot_list_camera_presets` | 列出标准与自定义相机预设。 |
461
+ | `keyshot_apply_camera_preset` | 根据预设创建或修改相机。 |
462
+ | `keyshot_set_environment` | 选择或调整环境、亮度和旋转。 |
463
+ | `keyshot_save_scene` | 将场景保存到受控输出路径。 |
435
464
 
436
465
  服务还提供一个产品渲染 MCP Prompt，以及一个说明 headless 工作流程的 MCP Resource。
466
+ 完整的 18 个工具参考由代码自动生成在 [`docs/TOOLS.md`](docs/TOOLS.md)。
437
467
  [`skills/keyshot-mcp`](skills/keyshot-mcp) 中的 Agent Skill 会指导兼容的 Agent 安装、
438
468
  诊断并安全使用这些工具。
439
469
 
440
470
  ### 配置
441
471
 
442
- | 环境变量 | 默认值 | 说明 |
443
- | --- | --- | --- |
444
- | `KEYSHOT_HEADLESS_EXE` | `D:\keyshot2025_183972\bin\keyshot_headless.exe` | 完整路径，或系统 `PATH` 中可执行的命令。 |
445
- | `KEYSHOT_OUTPUT_DIR` | `<用户目录>/Documents/KeyShot MCP Outputs` | 渲染图和场景副本的根目录。 |
446
- | `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | 只有明确设为 `true` 时才允许写到输出根目录之外。 |
447
- | `KEYSHOT_TIMEOUT_MS` | `600000` | 单次 KeyShot 进程超时时间。 |
448
- | `KEYSHOT_LICENSE_ARGS` | 空 | 可选启动参数；诊断结果不会回显具体内容。 |
449
- | `KEYSHOT_MATERIAL_PRESETS` | 内置 JSON | 可选的用户材质预设文件。 |
450
- | `KEYSHOT_CAMERA_PRESETS` | 内置 JSON | 可选的用户相机预设文件。 |
472
+ | 环境变量 | 默认值 | 说明 |
473
+ | -------------------------------- | ------------------------------------------ | ------------------------------------------------ |
474
+ | `KEYSHOT_HEADLESS_EXE` | Windows 上为 `keyshot_headless.exe` | 完整路径，或系统 `PATH` 中可执行的命令。 |
475
+ | `KEYSHOT_OUTPUT_DIR` | `<用户目录>/Documents/KeyShot MCP Outputs` | 渲染图和场景副本的根目录。 |
476
+ | `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | 只有明确设为 `true` 时才允许写到输出根目录之外。 |
477
+ | `KEYSHOT_TIMEOUT_MS` | `600000` | 单次 KeyShot 进程超时时间。 |
478
+ | `KEYSHOT_LICENSE_ARGS` | 空 | 可选启动参数；诊断结果不会回显具体内容。 |
479
+ | `KEYSHOT_MATERIAL_PRESETS` | 内置 JSON | 可选的用户材质预设文件。 |
480
+ | `KEYSHOT_CAMERA_PRESETS` | 内置 JSON | 可选的用户相机预设文件。 |
451
481
 
452
482
  所有 KeyShot 操作串行执行，减少许可证和文件冲突。输入模型和场景可以位于任意本地
453
483
  路径；生成的场景和图片默认只能写入 `KEYSHOT_OUTPUT_DIR`。系统会拒绝 `..`、同名前缀
package/SECURITY.md CHANGED
@@ -2,32 +2,62 @@
2
2
 
3
3
  ## English
4
4
 
5
- This MCP server runs KeyShot headless on the local machine. It can read scene/model files and write rendered images or saved scenes.
5
+ KeyShot MCP runs KeyShot headless on the local computer. It can read local scene,
6
+ model, material, and environment files and can write rendered images or scene copies.
6
7
 
7
- ### Safe Use
8
+ ### Model-provider data flow
8
9
 
9
- - Only connect this server to MCP clients you trust.
10
- - Only open scene/model/material files from trusted sources.
11
- - Do not put license keys, account passwords, or private tokens in prompts.
12
- - Prefer using the local KeyShot license configuration instead of passing license details through environment variables.
10
+ MCP clients normally send tool inputs and results to the model service selected by
11
+ the user. Scene metadata returned by inspection tools and images returned by
12
+ `keyshot_preview_render` may therefore leave the local computer through that MCP
13
+ client. Review the client and model provider's privacy settings before using private
14
+ or customer work.
13
15
 
14
- ### Reporting Issues
16
+ KeyShot MCP itself does not upload files, run a remote service, or collect telemetry.
17
+ It never requires license keys in prompts and does not expose arbitrary Python
18
+ execution.
15
19
 
16
- If you find a security issue, open a private advisory or contact the project maintainer directly before posting details publicly.
20
+ ### Safe use
21
+
22
+ - Connect the server only to MCP clients and model providers you trust.
23
+ - Open only scene, model, material, and environment files from trusted sources.
24
+ - Do not put license keys, account passwords, private tokens, or confidential asset
25
+ contents in prompts.
26
+ - Use KeyShot's existing local license configuration.
27
+ - Keep `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` disabled unless an external destination is
28
+ explicitly required and trusted.
29
+ - Review a preview before approving edits or final renders, and preserve source scenes.
30
+
31
+ ### Reporting issues
32
+
33
+ Report vulnerabilities through a private GitHub security advisory before posting
34
+ technical details publicly.
17
35
 
18
36
  ---
19
37
 
20
38
  ## 中文
21
39
 
22
- 这个 MCP 服务会在本机运行 KeyShot 无界面程序。它可以读取场景、模型、材质文件，也可以写入渲染图片或保存后的场景文件。
40
+ KeyShot MCP 在本机运行 KeyShot headless。它可以读取本地场景、模型、材质和环境
41
+ 文件，也可以写入渲染图片或场景副本。
42
+
43
+ ### 模型服务的数据流
44
+
45
+ MCP 客户端通常会把工具输入和结果发送给用户选择的模型服务。因此，场景检查工具
46
+ 返回的元数据，以及 `keyshot_preview_render` 返回的预览图片，可能通过 MCP 客户端
47
+ 离开本机。处理私有项目或客户项目之前，请先确认 MCP 客户端和模型服务商的隐私设置。
48
+
49
+ KeyShot MCP 本身不会上传文件、运行远程服务或收集遥测数据。它不会要求用户在提示词
50
+ 中提供许可证密钥，也不开放任意 Python 执行。
23
51
 
24
- ### 安全使用建议
52
+ ### 安全使用
25
53
 
26
- - 只把这个服务连接到你信任的 MCP 客户端。
27
- - 只打开来源可信的场景、模型和材质文件。
28
- - 不要在提示词里输入许可证密钥、账号密码或私人 token。
29
- - 优先使用本机已经配置好的 KeyShot 授权，不建议通过环境变量传递许可证细节。
54
+ - 只连接可信的 MCP 客户端和模型服务。
55
+ - 只打开来源可信的场景、模型、材质和环境文件。
56
+ - 不要在提示词中填写许可证密钥、账号密码、私有 Token 或保密素材内容。
57
+ - 使用 KeyShot 已有的本机许可证配置。
58
+ - 除非明确需要并信任外部位置，否则保持 `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` 关闭。
59
+ - 批准修改或最终渲染前先检查预览，并保留原始场景。
30
60
 
31
61
  ### 报告安全问题
32
62
 
33
- 如果发现安全问题，请先通过私密方式联系维护者，不要直接公开细节。
63
+ 请先通过 GitHub 私密安全公告报告漏洞，不要直接公开技术细节。
package/dist/config.js CHANGED
@@ -15,8 +15,10 @@ export function getConfig() {
15
15
  keyshotTimeoutMs: parsePositiveInt(process.env.KEYSHOT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
16
16
  tmpDir: path.join(projectRoot, "work", "tmp"),
17
17
  bridgeScriptPath: path.join(projectRoot, "scripts", "keyshot_bridge.py"),
18
- materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ?? path.join(projectRoot, "presets", "materials.json")),
19
- cameraPresetsPath: path.resolve(process.env.KEYSHOT_CAMERA_PRESETS ?? path.join(projectRoot, "presets", "cameras.json")),
18
+ materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ??
19
+ path.join(projectRoot, "presets", "materials.json")),
20
+ cameraPresetsPath: path.resolve(process.env.KEYSHOT_CAMERA_PRESETS ??
21
+ path.join(projectRoot, "presets", "cameras.json")),
20
22
  };
21
23
  }
22
24
  export function defaultOutputDir() {
package/dist/diagnostics.js CHANGED
@@ -25,7 +25,8 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
25
25
  checks.push(await presetCheck("camera-presets", "Camera presets", () => loadCameraPresets(config), config.cameraPresetsPath));
26
26
  checks.push(await presetCheck("material-presets", "Material presets", () => loadMaterialPresets(config), config.materialPresetsPath));
27
27
  let keyshotResult;
28
- if (resolvedExecutable && checks.find((check) => check.id === "bridge-script")?.ok) {
28
+ if (resolvedExecutable &&
29
+ checks.find((check) => check.id === "bridge-script")?.ok) {
29
30
  keyshotResult = await runStatus(config, { operation: "status" });
30
31
  }
31
32
  else {
@@ -47,10 +48,11 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
47
48
  severity: "error",
48
49
  message: keyshotResult.ok
49
50
  ? "KeyShot headless scripting started successfully."
50
- : keyshotResult.error ?? "KeyShot headless scripting did not start.",
51
+ : (keyshotResult.error ?? "KeyShot headless scripting did not start."),
51
52
  suggestion: keyshotResult.ok
52
53
  ? undefined
53
- : keyshotResult.suggestions?.[0] ?? "Open KeyShot normally, confirm the license is active, and retry.",
54
+ : (keyshotResult.suggestions?.[0] ??
55
+ "Open KeyShot normally, confirm the license is active, and retry."),
54
56
  });
55
57
  const ready = checks.every((check) => check.severity !== "error" || check.ok);
56
58
  const suggestions = unique([
@@ -87,8 +89,11 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
87
89
  checks,
88
90
  suggestions,
89
91
  },
90
- error: ready ? null : keyshotResult.error ?? "KeyShot MCP is not ready. Review the failed diagnostic checks.",
91
- errorCode: ready ? null : keyshotResult.errorCode ?? "DIAGNOSTIC_FAILED",
92
+ error: ready
93
+ ? null
94
+ : (keyshotResult.error ??
95
+ "KeyShot MCP is not ready. Review the failed diagnostic checks."),
96
+ errorCode: ready ? null : (keyshotResult.errorCode ?? "DIAGNOSTIC_FAILED"),
92
97
  suggestions,
93
98
  };
94
99
  }
@@ -106,11 +111,15 @@ function capabilitySummary(availableFunctions) {
106
111
  };
107
112
  }
108
113
  export async function resolveExecutable(command) {
109
- if (path.isAbsolute(command) || command.includes("/") || command.includes("\\")) {
114
+ if (path.isAbsolute(command) ||
115
+ command.includes("/") ||
116
+ command.includes("\\")) {
110
117
  const candidate = path.resolve(command);
111
- return await isFile(candidate) ? candidate : null;
118
+ return (await isFile(candidate)) ? candidate : null;
112
119
  }
113
- const pathEntries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
120
+ const pathEntries = (process.env.PATH ?? "")
121
+ .split(path.delimiter)
122
+ .filter(Boolean);
114
123
  const extensions = process.platform === "win32" && path.extname(command) === ""
115
124
  ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
116
125
  : [""];
@@ -125,7 +134,14 @@ export async function resolveExecutable(command) {
125
134
  }
126
135
  async function fileCheck(id, label, filePath, suggestion) {
127
136
  const ok = await isFile(filePath);
128
- return { id, label, ok, severity: "error", message: ok ? `Found: ${filePath}` : `Missing: ${filePath}`, suggestion: ok ? undefined : suggestion };
137
+ return {
138
+ id,
139
+ label,
140
+ ok,
141
+ severity: "error",
142
+ message: ok ? `Found: ${filePath}` : `Missing: ${filePath}`,
143
+ suggestion: ok ? undefined : suggestion,
144
+ };
129
145
  }
130
146
  async function outputWriteCheck(outputDir) {
131
147
  const probe = path.join(outputDir, `.keyshot-mcp-write-test-${randomUUID()}`);