keyshot-mcp 0.7.0 → 0.9.0

package/README.md

@@ -28,6 +28,7 @@ the local computer.
 - Apply materials directly or through a local material preset library.
 - Select environments, change brightness, and rotate the active environment.
 - Save edited scenes to a controlled output directory.
+- Prepare and render a product from a model or existing scene in one tool call.
 
 ### Requirements and compatibility
 
@@ -40,7 +41,7 @@ the local computer.
 
 ### Install
 
-The current release is `0.7.0`.
+The current release is `0.9.0`.
 
 #### Option 1: run with npx
 
@@ -51,7 +52,7 @@ This requires no global npm installation:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.7.0"],
+      "args": ["-y", "keyshot-mcp@0.9.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -63,7 +64,7 @@ This requires no global npm installation:
 #### Option 2: install globally
 
 ```bash
-npm install -g keyshot-mcp@0.7.0
+npm install -g keyshot-mcp@0.9.0
 ```
 
 ```json
@@ -112,14 +113,14 @@ The following prompt can be pasted into a coding agent that is allowed to edit
 the MCP client configuration:
 
 ```text
-Install KeyShot MCP 0.7.0 and configure it in my MCP client.
+Install KeyShot MCP 0.9.0 and configure it in my MCP client.
 
 1. Find the local KeyShot headless executable.
 2. Add an MCP server named "keyshot" that runs:
-   npx -y keyshot-mcp@0.7.0
+   npx -y keyshot-mcp@0.9.0
 3. Set KEYSHOT_HEADLESS_EXE to the executable path.
 4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
-5. Restart or reload the MCP client, then call keyshot_status.
+5. Restart or reload the MCP client, call keyshot_status, then use keyshot_product_render for a one-click product render.
 6. Do not upload or publish any KeyShot scenes, models, renders, or license data.
 ```
 
@@ -128,7 +129,7 @@ Install KeyShot MCP 0.7.0 and configure it in my MCP client.
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `KEYSHOT_HEADLESS_EXE` | `keyshot_headless.exe` on Windows | Absolute executable path or a command available on `PATH`. |
-| `KEYSHOT_OUTPUT_DIR` | Package-local `outputs` | Root directory for rendered images and saved scenes. |
+| `KEYSHOT_OUTPUT_DIR` | `~/Documents/KeyShot MCP Outputs` | Root directory for rendered images and saved scenes. |
 | `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | Allows output paths outside `KEYSHOT_OUTPUT_DIR` when explicitly set to `true`. |
 | `KEYSHOT_TIMEOUT_MS` | `600000` | Timeout for one KeyShot headless process. |
 | `KEYSHOT_LICENSE_ARGS` | empty | Optional additional KeyShot launch arguments. |
@@ -139,11 +140,17 @@ Relative output paths are resolved inside `KEYSHOT_OUTPUT_DIR`. Parent traversal
 adjacent-prefix paths, and symbolic-link escapes are rejected by default. Input
 scene, model, material, and environment paths may be located elsewhere.
 
+Run `keyshot_status` after installation. It reports the MCP and KeyShot
+versions, resolved executable, output write access, preset validity, headless
+startup result, and actionable suggestions. Additional KeyShot launch arguments
+are never included in the diagnostic output.
+
 ### Tools
 
 | Tool | Purpose |
 | --- | --- |
-| `keyshot_status` | Verify that KeyShot headless can start and report its version. |
+| `keyshot_status` | Diagnose local configuration, output access, presets, and KeyShot headless startup. |
+| `keyshot_product_render` | Prepare, save, and render a model or existing scene in one headless process. |
 | `keyshot_inspect_scene` | Inspect objects, cameras, materials, model sets, and references. |
 | `keyshot_list_cameras` | List available camera names. |
 | `keyshot_render` | Render one image. |
@@ -160,9 +167,61 @@ scene, model, material, and environment paths may be located elsewhere.
 | `keyshot_set_environment` | Select or adjust an environment, brightness, or rotation. |
 | `keyshot_save_scene` | Save a scene to a new output path. |
 
-The server also exposes a `keyshot_product_render` MCP prompt and a
+The server exposes 17 tools, a `keyshot_product_render` MCP prompt, and a
 `keyshot://workflow` resource.
 
+### One-click product render
+
+In an MCP client, a designer can use a natural-language request:
+
+```text
+Turn C:\models\speaker.obj into a product render. Center it, place it on the
+ground, use the Isometric camera preset, save the KeyShot scene, and render a
+1600 x 1200 PNG with 128 samples.
+```
+
+The `keyshot_product_render` tool accepts either `modelPath` or `scenePath`. New
+models default to centered and grounded geometry with a `Product Hero`
+isometric camera. Existing scenes keep their current camera, materials, and
+environment unless explicit changes are requested.
+
+One-click product rendering defaults to the `standard` quality preset. All
+rendering tools accept:
+
+| Preset | Resolution | Samples |
+| --- | ---: | ---: |
+| `preview` | 960 × 540 | 16 |
+| `standard` | 1920 × 1080 | 64 |
+| `final` | 3840 × 2160 | 256 |
+
+Explicit `width`, `height`, or `samples` values override the corresponding
+preset value. `maxTimeSeconds` replaces preset samples. Explicit `samples` and
+`maxTimeSeconds` cannot be used together.
+
+```json
+{
+  "modelPath": "C:/models/speaker.obj",
+  "outputScenePath": "speaker-product.bip",
+  "outputPath": "speaker-product.png",
+  "materialAssignments": [
+    { "objectName": "Body", "presetName": "Brushed Steel" }
+  ],
+  "cameraPresetName": "Isometric",
+  "focalLength": 55,
+  "brightness": 1.2,
+  "rotation": 45,
+  "qualityPreset": "standard"
+}
+```
+
+Use `renderMode: "allCameras"` with `outputDir` to render every named camera.
+Generated names are derived from the source filename when output paths are
+omitted. If an automatically named result exists, the scene and image receive
+the same `-2`, `-3`, and later suffix. Explicit output paths remain protected
+and return an error when occupied; set `overwrite: true` only when replacement
+is intentional. Material assignments always require an
+explicit object and never overwrite the entire model implicitly.
+
 ### Product composition examples
 
 Import a model and prepare its initial composition:
@@ -222,7 +281,8 @@ them.
 The repository includes a smoke test built from generated cube geometry in
 `examples/demo`. It verifies startup, import composition, scene inspection,
 camera presets, focal length, field of view, camera distance, environment
-rotation, scene saving, camera discovery, and real PNG rendering:
+rotation, scene saving, camera discovery, one-click model rendering, one-click
+existing-scene rendering, and real PNG output:
 
 ```bash
 npm run smoke:keyshot
@@ -254,18 +314,6 @@ Linux.
 - Add depth-of-field and additional lens controls when stable headless APIs are
   available.
 
-### Star history
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="assets/star-history-light.svg">
-  <img alt="GitHub star history for truman-t3/keyshot-mcp" src="assets/star-history-light.svg">
-</picture>
-
-The chart uses the actual `starred_at` date for each GitHub star and displays a
-cumulative step line. A weekly GitHub Action updates it only when detailed
-stargazer dates are available.
-
 ### License and security
 
 Released under the [MIT License](LICENSE). See [SECURITY.md](SECURITY.md) for
@@ -273,6 +321,18 @@ security guidance and [CONTRIBUTING.md](CONTRIBUTING.md) for development notes.
 Do not commit KeyShot licenses, private scenes, customer assets, or unpublished
 renders.
 
+### Trademark and project status
+
+KeyShot is a trademark of KeyShot ApS and/or KeyShot Inc. This is an independent,
+open-source community project and is not affiliated with, endorsed by, or
+sponsored by KeyShot.
+
+This project provides only an MCP integration. It does not include KeyShot
+Studio, KeyShot assets, or a KeyShot license. Users must install and license
+KeyShot Studio separately and comply with the applicable KeyShot terms. Do not
+use this project to bypass licensing, share credentials, or redistribute KeyShot
+software or proprietary resources.
+
 ---
 
 ## 中文
@@ -291,6 +351,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
 - 直接应用材质，或使用本地材质预设库。
 - 选择环境、调整亮度并旋转当前环境。
 - 将修改后的场景保存到受控输出目录。
+- 通过一次工具调用完成模型或现有场景的产品构图与渲染。
 
 ### 运行要求与兼容性
 
@@ -302,7 +363,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
 
 ### 安装
 
-当前版本为 `0.7.0`。
+当前版本为 `0.9.0`。
 
 #### 方式一：使用 npx
 
@@ -313,7 +374,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.7.0"],
+      "args": ["-y", "keyshot-mcp@0.9.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -325,7 +386,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
 #### 方式二：全局安装
 
 ```bash
-npm install -g keyshot-mcp@0.7.0
+npm install -g keyshot-mcp@0.9.0
 ```
 
 ```json
@@ -373,14 +434,14 @@ pnpm build
 下面的提示词适用于有权限修改 MCP 客户端配置的编程 Agent：
 
 ```text
-请帮我安装 KeyShot MCP 0.7.0，并添加到我的 MCP 客户端。
+请帮我安装 KeyShot MCP 0.9.0，并添加到我的 MCP 客户端。
 
 1. 查找本机 KeyShot headless 可执行文件。
 2. 添加名为 keyshot 的 MCP server，运行：
-   npx -y keyshot-mcp@0.7.0
+   npx -y keyshot-mcp@0.9.0
 3. 将 KEYSHOT_HEADLESS_EXE 设置为可执行文件路径。
 4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
-5. 重启或重新加载 MCP 客户端，然后调用 keyshot_status。
+5. 重启或重新加载 MCP 客户端，调用 keyshot_status，然后使用 keyshot_product_render 一键完成产品出图。
 6. 不要上传或发布任何 KeyShot 场景、模型、渲染图或许可证数据。
 ```
 
@@ -389,7 +450,7 @@ pnpm build
 | 环境变量 | 默认值 | 用途 |
 | --- | --- | --- |
 | `KEYSHOT_HEADLESS_EXE` | Windows 上为 `keyshot_headless.exe` | KeyShot headless 绝对路径，或系统 `PATH` 中的命令。 |
-| `KEYSHOT_OUTPUT_DIR` | 包内 `outputs` | 渲染图和已保存场景的根目录。 |
+| `KEYSHOT_OUTPUT_DIR` | `~/Documents/KeyShot MCP Outputs` | 渲染图和已保存场景的根目录。 |
 | `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | 明确设为 `true` 时允许写入输出根目录之外。 |
 | `KEYSHOT_TIMEOUT_MS` | `600000` | 单个 KeyShot headless 进程的超时时间。 |
 | `KEYSHOT_LICENSE_ARGS` | 空 | 可选的 KeyShot 启动参数。 |
@@ -399,11 +460,16 @@ pnpm build
 相对输出路径会自动放入 `KEYSHOT_OUTPUT_DIR`。默认拒绝 `..`、相邻同名前缀目录和
 软链接逃逸。输入场景、模型、材质和环境文件可位于其他目录。
 
+安装后调用 `keyshot_status`，可检查 MCP 与 KeyShot 版本、实际可执行文件路径、
+输出目录写入权限、预设文件和 headless 启动状态，并获得可直接执行的修复建议。
+诊断结果不会回显额外的 KeyShot 启动参数。
+
 ### MCP 工具
 
 | 工具 | 用途 |
 | --- | --- |
-| `keyshot_status` | 检查 KeyShot headless 是否可启动并读取版本。 |
+| `keyshot_status` | 诊断本地配置、输出权限、预设文件和 KeyShot headless 启动状态。 |
+| `keyshot_product_render` | 在一个 headless 进程中完成模型或场景准备、保存和渲染。 |
 | `keyshot_inspect_scene` | 检查对象、相机、材质、模型集和外部引用。 |
 | `keyshot_list_cameras` | 列出场景中的相机名称。 |
 | `keyshot_render` | 渲染一张图片。 |
@@ -420,7 +486,54 @@ pnpm build
 | `keyshot_set_environment` | 选择环境并调整亮度或旋转角度。 |
 | `keyshot_save_scene` | 将场景保存到新的输出路径。 |
 
-服务还提供 `keyshot_product_render` MCP 提示词和 `keyshot://workflow` 资源。
+服务共提供 17 个工具，并提供 `keyshot_product_render` MCP 提示词和
+`keyshot://workflow` 资源。
+
+### 一键产品出图
+
+设计师可以直接在支持 MCP 的 Agent 中描述需求：
+
+```text
+把 C:\models\speaker.obj 做成产品渲染图。自动居中、贴地，使用 Isometric
+相机预设，保存 KeyShot 场景，并用 128 采样渲染一张 1600 x 1200 PNG。
+```
+
+`keyshot_product_render` 可以接收 `modelPath` 或 `scenePath`。新模型默认自动居中、
+贴地并创建名为 `Product Hero` 的等轴测相机；已有场景默认保留当前相机、材质和环境，
+只有明确提供参数时才修改。
+
+一键产品出图未指定质量时默认使用 `standard`。全部渲染工具都支持：
+
+| 预设 | 分辨率 | 采样 |
+| --- | ---: | ---: |
+| `preview` | 960 × 540 | 16 |
+| `standard` | 1920 × 1080 | 64 |
+| `final` | 3840 × 2160 | 256 |
+
+显式填写的 `width`、`height` 或 `samples` 会分别覆盖预设值。
+`maxTimeSeconds` 会替代预设采样；不能同时显式提供 `samples` 和
+`maxTimeSeconds`。
+
+```json
+{
+  "modelPath": "C:/models/speaker.obj",
+  "outputScenePath": "speaker-product.bip",
+  "outputPath": "speaker-product.png",
+  "materialAssignments": [
+    { "objectName": "Body", "presetName": "Brushed Steel" }
+  ],
+  "cameraPresetName": "Isometric",
+  "focalLength": 55,
+  "brightness": 1.2,
+  "rotation": 45,
+  "qualityPreset": "standard"
+}
+```
+
+将 `renderMode` 设为 `allCameras` 并提供 `outputDir`，即可渲染场景中的全部命名相机。
+省略输出路径时会根据源文件名自动生成。自动名称已存在时，场景和图片会统一增加
+`-2`、`-3` 等编号；用户明确填写的路径仍会严格防止覆盖。只有明确设置
+`overwrite: true` 才会替换。材质指定必须包含明确的对象，不会隐式覆盖整个模型。
 
 ### 产品构图示例
 
@@ -474,7 +587,7 @@ pnpm build
 
 仓库提供基于 `examples/demo` 生成立方体几何体的 smoke test，用于验证 KeyShot
 启动、导入构图、场景检查、相机预设、焦距、视野角、相机距离、环境旋转、场景保存、
-相机发现和真实 PNG 渲染：
+相机发现、模型一键出图、现有场景一键渲染全部相机和真实 PNG 输出：
 
 ```bash
 npm run smoke:keyshot
@@ -503,19 +616,17 @@ CI 在 Windows 和 Ubuntu 上使用 Node.js 20、24 运行。Linux CI 验证 MCP
 - 验证 macOS 安装和 headless 行为。
 - 在 headless API 稳定支持后增加景深和更多镜头控制。
 
-### 星标趋势
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="assets/star-history-light.svg">
-  <img alt="truman-t3/keyshot-mcp 的 GitHub 星标趋势" src="assets/star-history-light.svg">
-</picture>
-
-趋势图使用每颗 GitHub Star 的真实 `starred_at` 日期绘制累计阶梯线。GitHub Actions
-每周检查一次，并且只在能够取得逐星日期时更新。
-
 ### 许可证与安全
 
 项目采用 [MIT License](LICENSE)。安全说明见 [SECURITY.md](SECURITY.md)，开发说明
 见 [CONTRIBUTING.md](CONTRIBUTING.md)。请勿提交 KeyShot 许可证、私有场景、客户素材
 或未公开渲染图。
+
+### 商标与项目性质
+
+KeyShot 是 KeyShot ApS 和/或 KeyShot Inc. 的商标。本项目是独立的开源社区项目，
+与 KeyShot 官方无隶属、认可、赞助或其他合作关系。
+
+本项目仅提供 MCP 集成功能，不包含 KeyShot Studio、KeyShot 官方素材或 KeyShot
+许可证。用户必须自行安装并合法授权 KeyShot Studio，同时遵守适用的 KeyShot 条款。
+不得使用本项目绕过许可证、共享账号凭据，或重新分发 KeyShot 软件及其专有资源。

package/dist/cli/status.js

@@ -1,5 +1,5 @@
 import { getConfig } from "../config.js";
-import { runKeyShotSerialized } from "../runner.js";
-const result = await runKeyShotSerialized(getConfig(), { operation: "status" });
+import { runKeyShotDiagnostics } from "../diagnostics.js";
+const result = await runKeyShotDiagnostics(getConfig());
 console.log(JSON.stringify(result, null, 2));
 process.exit(result.ok ? 0 : 1);

package/dist/config.js

@@ -1,10 +1,11 @@
 import path from "node:path";
+import os from "node:os";
 import { fileURLToPath } from "node:url";
 const DEFAULT_KEYSHOT_EXE = process.platform === "win32" ? "keyshot_headless.exe" : "keyshot_headless";
 const DEFAULT_TIMEOUT_MS = 600_000;
 export function getConfig() {
     const projectRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
-    const keyshotOutputDir = path.resolve(process.env.KEYSHOT_OUTPUT_DIR ?? path.join(projectRoot, "outputs"));
+    const keyshotOutputDir = path.resolve(process.env.KEYSHOT_OUTPUT_DIR ?? defaultOutputDir());
     return {
         projectRoot,
         keyshotHeadlessExe: process.env.KEYSHOT_HEADLESS_EXE ?? DEFAULT_KEYSHOT_EXE,
@@ -18,6 +19,9 @@ export function getConfig() {
         cameraPresetsPath: path.resolve(process.env.KEYSHOT_CAMERA_PRESETS ?? path.join(projectRoot, "presets", "cameras.json")),
     };
 }
+export function defaultOutputDir() {
+    return path.join(os.homedir(), "Documents", "KeyShot MCP Outputs");
+}
 function parseBoolean(value) {
     return ["1", "true", "yes", "on"].includes((value ?? "").trim().toLowerCase());
 }

package/dist/diagnostics.js

@@ -0,0 +1,191 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { loadCameraPresets } from "./camera-presets.js";
+import { loadMaterialPresets } from "./presets.js";
+import { runKeyShotSerialized } from "./runner.js";
+import { VERSION } from "./version.js";
+export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerialized) {
+    const checks = [];
+    const resolvedExecutable = await resolveExecutable(config.keyshotHeadlessExe);
+    checks.push({
+        id: "keyshot-executable",
+        label: "KeyShot headless executable",
+        ok: resolvedExecutable !== null,
+        severity: "error",
+        message: resolvedExecutable
+            ? `Resolved KeyShot headless executable: ${resolvedExecutable}`
+            : `KeyShot headless executable was not found: ${config.keyshotHeadlessExe}`,
+        suggestion: resolvedExecutable
+            ? undefined
+            : "Set KEYSHOT_HEADLESS_EXE to the full path of keyshot_headless.exe and restart the MCP client.",
+    });
+    checks.push(await fileCheck("bridge-script", "KeyShot bridge script", config.bridgeScriptPath, "Reinstall keyshot-mcp so scripts/keyshot_bridge.py is included."));
+    checks.push(await outputWriteCheck(config.keyshotOutputDir));
+    checks.push(await presetCheck("camera-presets", "Camera presets", () => loadCameraPresets(config), config.cameraPresetsPath));
+    checks.push(await presetCheck("material-presets", "Material presets", () => loadMaterialPresets(config), config.materialPresetsPath));
+    let keyshotResult;
+    if (resolvedExecutable && checks.find((check) => check.id === "bridge-script")?.ok) {
+        keyshotResult = await runStatus(config, { operation: "status" });
+    }
+    else {
+        keyshotResult = {
+            ok: false,
+            data: null,
+            outputFiles: [],
+            warnings: [],
+            keyshotStdoutTail: "",
+            error: "KeyShot startup was skipped because a required local file was not available.",
+            errorCode: "DIAGNOSTIC_PREREQUISITE_FAILED",
+            suggestions: [],
+        };
+    }
+    checks.push({
+        id: "keyshot-startup",
+        label: "KeyShot headless startup",
+        ok: keyshotResult.ok,
+        severity: "error",
+        message: keyshotResult.ok
+            ? "KeyShot headless scripting started successfully."
+            : keyshotResult.error ?? "KeyShot headless scripting did not start.",
+        suggestion: keyshotResult.ok
+            ? undefined
+            : keyshotResult.suggestions?.[0] ?? "Open KeyShot normally, confirm the license is active, and retry.",
+    });
+    const ready = checks.every((check) => check.severity !== "error" || check.ok);
+    const suggestions = unique([
+        ...checks.flatMap((check) => !check.ok && check.suggestion ? [check.suggestion] : []),
+        ...(keyshotResult.suggestions ?? []),
+    ]);
+    const bridgeData = keyshotResult.data && typeof keyshotResult.data === "object"
+        ? keyshotResult.data
+        : {};
+    const availableFunctions = Array.isArray(bridgeData.availableFunctions)
+        ? bridgeData.availableFunctions.filter((name) => typeof name === "string")
+        : [];
+    const { availableFunctions: _omittedFunctions, ...bridgeSummary } = bridgeData;
+    return {
+        ...keyshotResult,
+        ok: ready,
+        data: {
+            ...bridgeSummary,
+            availableFunctionCount: availableFunctions.length,
+            capabilities: capabilitySummary(availableFunctions),
+            serverVersion: VERSION,
+            ready,
+            config: {
+                keyshotHeadlessExe: config.keyshotHeadlessExe,
+                resolvedExecutable,
+                outputDir: config.keyshotOutputDir,
+                allowExternalOutputs: config.keyshotAllowExternalOutputs,
+                timeoutMs: config.keyshotTimeoutMs,
+                licenseArgsConfigured: config.keyshotLicenseArgs.length > 0,
+                bridgeScriptPath: config.bridgeScriptPath,
+                cameraPresetsPath: config.cameraPresetsPath,
+                materialPresetsPath: config.materialPresetsPath,
+            },
+            checks,
+            suggestions,
+        },
+        error: ready ? null : keyshotResult.error ?? "KeyShot MCP is not ready. Review the failed diagnostic checks.",
+        errorCode: ready ? null : keyshotResult.errorCode ?? "DIAGNOSTIC_FAILED",
+        suggestions,
+    };
+}
+function capabilitySummary(availableFunctions) {
+    const available = new Set(availableFunctions);
+    return {
+        render: available.has("renderImage"),
+        inspectObjects: available.has("getObjects"),
+        cameras: available.has("getCameras") && available.has("newCamera"),
+        standardViews: available.has("setStandardView"),
+        importModel: available.has("importFile"),
+        materials: available.has("setObjectMaterial"),
+        renderOptions: available.has("getRenderOptions"),
+        environments: available.has("getActiveEnvironment"),
+    };
+}
+export async function resolveExecutable(command) {
+    if (path.isAbsolute(command) || command.includes("/") || command.includes("\\")) {
+        const candidate = path.resolve(command);
+        return await isFile(candidate) ? candidate : null;
+    }
+    const pathEntries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const extensions = process.platform === "win32" && path.extname(command) === ""
+        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+        : [""];
+    for (const entry of pathEntries) {
+        for (const extension of extensions) {
+            const candidate = path.join(entry.replace(/^"|"$/g, ""), `${command}${extension}`);
+            if (await isFile(candidate))
+                return path.resolve(candidate);
+        }
+    }
+    return null;
+}
+async function fileCheck(id, label, filePath, suggestion) {
+    const ok = await isFile(filePath);
+    return { id, label, ok, severity: "error", message: ok ? `Found: ${filePath}` : `Missing: ${filePath}`, suggestion: ok ? undefined : suggestion };
+}
+async function outputWriteCheck(outputDir) {
+    const probe = path.join(outputDir, `.keyshot-mcp-write-test-${randomUUID()}`);
+    try {
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.writeFile(probe, "ok", "utf8");
+        await fs.rm(probe, { force: true });
+        return {
+            id: "output-directory",
+            label: "Output directory",
+            ok: true,
+            severity: "error",
+            message: `Output directory is writable: ${outputDir}`,
+        };
+    }
+    catch (error) {
+        await fs.rm(probe, { force: true }).catch(() => undefined);
+        return {
+            id: "output-directory",
+            label: "Output directory",
+            ok: false,
+            severity: "error",
+            message: `Output directory is not writable: ${outputDir} (${errorMessage(error)})`,
+            suggestion: "Set KEYSHOT_OUTPUT_DIR to a local folder where the current user can create files.",
+        };
+    }
+}
+async function presetCheck(id, label, loader, source) {
+    try {
+        const presets = await loader();
+        return {
+            id,
+            label,
+            ok: true,
+            severity: "warning",
+            message: `${label} loaded successfully (${presets.length}) from ${source}`,
+        };
+    }
+    catch (error) {
+        return {
+            id,
+            label,
+            ok: false,
+            severity: "warning",
+            message: errorMessage(error),
+            suggestion: `Fix the JSON syntax in ${source}, or remove the custom environment variable to use built-in presets.`,
+        };
+    }
+}
+async function isFile(value) {
+    try {
+        return (await fs.stat(value)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.js

@@ -7,8 +7,11 @@ import { runKeyShotSerialized } from "./runner.js";
 import { runRenderQueue } from "./queue.js";
 import { loadMaterialPresets, findMaterialPreset } from "./presets.js";
 import { loadCameraPresets, findCameraPreset } from "./camera-presets.js";
+import { prepareProductRenderRequest } from "./product-render.js";
 import { VERSION } from "./version.js";
-import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, applyCameraPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, listCameraPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderAllCamerasSchema, renderAllCamerasInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraInputSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
+import { applyRenderQuality } from "./quality.js";
+import { runKeyShotDiagnostics } from "./diagnostics.js";
+import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, applyCameraPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, listCameraPresetsSchema, productRenderInputSchema, productRenderSchema, renderQueueSchema, renderQueueInputSchema, renderAllCamerasSchema, renderAllCamerasInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraInputSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
 const config = getConfig();
 const server = new McpServer({
     name: "keyshot-mcp",
@@ -39,6 +42,7 @@ server.registerPrompt("keyshot_product_render", {
     title: "Render a KeyShot product scene",
     description: "Create a practical prompt for rendering or batch-rendering a KeyShot product scene.",
     argsSchema: {
+        modelPath: scenePathSchema.shape.scenePath.optional(),
         scenePath: scenePathSchema.shape.scenePath.optional(),
         goal: scenePathSchema.shape.scenePath.optional(),
     },
@@ -50,32 +54,46 @@ server.registerPrompt("keyshot_product_render", {
                 type: "text",
                 text: [
                     "Use KeyShot MCP to prepare a product render.",
-                    args.scenePath ? `Scene path: ${args.scenePath}` : "Ask me for the KeyShot scene path first.",
+                    args.modelPath
+                        ? `Model path: ${args.modelPath}`
+                        : args.scenePath
+                            ? `Scene path: ${args.scenePath}`
+                            : "Ask me for either a model path or a KeyShot scene path first.",
                     args.goal ? `Goal: ${args.goal}` : "Inspect the scene, choose a suitable camera, then render a PNG preview.",
-                    "Start with keyshot_status, then keyshot_inspect_scene, then render or batch render as needed.",
+                    "Call the keyshot_product_render tool for the complete workflow. Use the lower-level tools only when individual steps need manual control.",
                 ].join("\n"),
             },
         },
     ],
 }));
-server.tool("keyshot_status", "Check KeyShot headless availability and script startup.", {}, async () => toolResponse(await runKeyShotSerialized(config, { operation: "status" })));
+server.tool("keyshot_status", "Diagnose the local KeyShot MCP installation and verify headless startup.", {}, async () => toolResponse(await runKeyShotDiagnostics(config)));
+server.tool("keyshot_product_render", "Prepare and render a product from either a model file or an existing KeyShot scene in one headless process.", productRenderInputSchema.shape, async (args) => {
+    try {
+        const parsed = productRenderSchema.parse(args);
+        const request = await prepareProductRenderRequest(config, parsed);
+        return toolResponse(await runKeyShotSerialized(config, request));
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+});
 server.tool("keyshot_inspect_scene", "Open a KeyShot scene and return available objects, cameras, materials and scene metadata.", scenePathSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "inspect_scene", ...args })));
 server.tool("keyshot_list_cameras", "Open a KeyShot scene and return the list of available camera names (useful before batch rendering).", listCamerasSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "list_cameras", ...args })));
 server.tool("keyshot_render", "Render a KeyShot scene to an image file.", renderSchema.shape, async (args) => {
     const parsed = renderInputSchema.parse(args);
-    return toolResponse(await runKeyShotSerialized(config, { operation: "render", ...parsed }));
+    return toolResponse(await runKeyShotSerialized(config, { operation: "render", ...applyRenderQuality(parsed) }));
 });
 server.tool("keyshot_render_queue", "Render several jobs sequentially. Stops at the first failure unless continueOnError is set.", renderQueueSchema.shape, async (args) => {
     const parsed = renderQueueInputSchema.parse(args);
-    return toolResponse(await runRenderQueue(config, parsed.jobs, { continueOnError: parsed.continueOnError ?? false }));
+    return toolResponse(await runRenderQueue(config, parsed.jobs.map((job) => applyRenderQuality(job)), { continueOnError: parsed.continueOnError ?? false }));
 });
 server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyShot scene into an output directory.", batchRenderSchema.shape, async (args) => {
     const parsed = batchRenderInputSchema.parse(args);
-    return toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...parsed }));
+    return toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...applyRenderQuality(parsed) }));
 });
 server.tool("keyshot_render_all_cameras", "Discover every camera in one KeyShot scene and render each view into an output directory.", renderAllCamerasSchema.shape, async (args) => {
     const parsed = renderAllCamerasInputSchema.parse(args);
-    return toolResponse(await runKeyShotSerialized(config, { operation: "render_all_cameras", ...parsed }));
+    return toolResponse(await runKeyShotSerialized(config, { operation: "render_all_cameras", ...applyRenderQuality(parsed) }));
 });
 server.tool("keyshot_import_model", "Import a model into an optional base scene, optionally center and ground it, adjust the camera or environment, and save the resulting scene.", importModelSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, {
     operation: "import_model",