keyshot-mcp 0.8.0 → 0.9.0

package/README.md

@@ -41,7 +41,7 @@ the local computer.
 
 ### Install
 
-The current release is `0.8.0`.
+The current release is `0.9.0`.
 
 #### Option 1: run with npx
 
@@ -52,7 +52,7 @@ This requires no global npm installation:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.8.0"],
+      "args": ["-y", "keyshot-mcp@0.9.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -64,7 +64,7 @@ This requires no global npm installation:
 #### Option 2: install globally
 
 ```bash
-npm install -g keyshot-mcp@0.8.0
+npm install -g keyshot-mcp@0.9.0
 ```
 
 ```json
@@ -113,11 +113,11 @@ The following prompt can be pasted into a coding agent that is allowed to edit
 the MCP client configuration:
 
 ```text
-Install KeyShot MCP 0.8.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.8.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, call keyshot_status, then use keyshot_product_render for a one-click product render.
@@ -129,7 +129,7 @@ Install KeyShot MCP 0.8.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. |
@@ -140,11 +140,16 @@ 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. |
@@ -180,6 +185,19 @@ 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",
@@ -192,16 +210,16 @@ environment unless explicit changes are requested.
   "focalLength": 55,
   "brightness": 1.2,
   "rotation": 45,
-  "width": 1600,
-  "height": 1200,
-  "samples": 128
+  "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. Existing files are protected by default; set `overwrite: true` only
-when replacement is intentional. Material assignments always require an
+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
@@ -345,7 +363,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
 
 ### 安装
 
-当前版本为 `0.8.0`。
+当前版本为 `0.9.0`。
 
 #### 方式一：使用 npx
 
@@ -356,7 +374,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.8.0"],
+      "args": ["-y", "keyshot-mcp@0.9.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -368,7 +386,7 @@ headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场
 #### 方式二：全局安装
 
 ```bash
-npm install -g keyshot-mcp@0.8.0
+npm install -g keyshot-mcp@0.9.0
 ```
 
 ```json
@@ -416,11 +434,11 @@ pnpm build
 下面的提示词适用于有权限修改 MCP 客户端配置的编程 Agent：
 
 ```text
-请帮我安装 KeyShot MCP 0.8.0，并添加到我的 MCP 客户端。
+请帮我安装 KeyShot MCP 0.9.0，并添加到我的 MCP 客户端。
 
 1. 查找本机 KeyShot headless 可执行文件。
 2. 添加名为 keyshot 的 MCP server，运行：
-   npx -y keyshot-mcp@0.8.0
+   npx -y keyshot-mcp@0.9.0
 3. 将 KEYSHOT_HEADLESS_EXE 设置为可执行文件路径。
 4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
 5. 重启或重新加载 MCP 客户端，调用 keyshot_status，然后使用 keyshot_product_render 一键完成产品出图。
@@ -432,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 启动参数。 |
@@ -442,11 +460,15 @@ 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` | 列出场景中的相机名称。 |
@@ -480,6 +502,18 @@ pnpm build
 贴地并创建名为 `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",
@@ -492,14 +526,13 @@ pnpm build
   "focalLength": 55,
   "brightness": 1.2,
   "rotation": 45,
-  "width": 1600,
-  "height": 1200,
-  "samples": 128
+  "qualityPreset": "standard"
 }
 ```
 
 将 `renderMode` 设为 `allCameras` 并提供 `outputDir`，即可渲染场景中的全部命名相机。
-省略输出路径时会根据源文件名自动生成。默认不会覆盖已有文件，只有明确设置
+省略输出路径时会根据源文件名自动生成。自动名称已存在时，场景和图片会统一增加
+`-2`、`-3` 等编号；用户明确填写的路径仍会严格防止覆盖。只有明确设置
 `overwrite: true` 才会替换。材质指定必须包含明确的对象，不会隐式覆盖整个模型。
 
 ### 产品构图示例

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

@@ -9,6 +9,8 @@ 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 { 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({
@@ -64,7 +66,7 @@ server.registerPrompt("keyshot_product_render", {
         },
     ],
 }));
-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);
@@ -79,19 +81,19 @@ server.tool("keyshot_inspect_scene", "Open a KeyShot scene and return available
 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",

package/dist/output-collisions.js

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const PRODUCT_OUTPUT_FIELDS = ["outputScenePath", "outputPath", "outputDir"];
+export async function allocateAutomaticProductOutputs(request) {
+    const configured = Array.isArray(request._automaticOutputFields) ? request._automaticOutputFields : [];
+    const automatic = new Set(configured.filter((field) => PRODUCT_OUTPUT_FIELDS.includes(field)));
+    const result = { ...request };
+    delete result._automaticOutputFields;
+    if (result.overwrite === true || automatic.size === 0)
+        return result;
+    for (let sequence = 1; sequence < 10_000; sequence += 1) {
+        const candidates = new Map();
+        for (const field of automatic) {
+            const value = result[field];
+            if (typeof value === "string")
+                candidates.set(field, numberedPath(value, field, sequence));
+        }
+        const occupied = await Promise.all([...candidates.values()].map(exists));
+        if (occupied.some(Boolean))
+            continue;
+        for (const [field, value] of candidates)
+            result[field] = value;
+        return result;
+    }
+    throw new Error("Could not find an available automatic output name after 9999 attempts.");
+}
+function numberedPath(value, field, sequence) {
+    if (sequence === 1)
+        return value;
+    if (field === "outputDir")
+        return `${value}-${sequence}`;
+    const parsed = path.parse(value);
+    return path.join(parsed.dir, `${parsed.name}-${sequence}${parsed.ext}`);
+}
+async function exists(value) {
+    try {
+        await fs.lstat(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/product-render.js

@@ -1,12 +1,20 @@
 import path from "node:path";
 import { findCameraPreset, loadCameraPresets } from "./camera-presets.js";
 import { findMaterialPreset, loadMaterialPresets } from "./presets.js";
+import { applyRenderQuality } from "./quality.js";
 export async function prepareProductRenderRequest(config, input) {
     const sourcePath = input.modelPath ?? input.scenePath;
     const stem = safeStem(sourcePath);
     const format = input.format ?? "png";
     const renderMode = input.renderMode ?? "single";
-    const request = {
+    const automaticOutputFields = [];
+    if (!input.outputScenePath)
+        automaticOutputFields.push("outputScenePath");
+    if (renderMode === "single" && !input.outputPath)
+        automaticOutputFields.push("outputPath");
+    if (renderMode === "allCameras" && !input.outputDir)
+        automaticOutputFields.push("outputDir");
+    const request = applyRenderQuality({
         ...input,
         operation: "product_render",
         renderMode,
@@ -14,7 +22,8 @@ export async function prepareProductRenderRequest(config, input) {
         outputScenePath: input.outputScenePath ?? `${stem}-product.bip`,
         overwrite: input.overwrite ?? false,
         continueOnError: input.continueOnError ?? true,
-    };
+        _automaticOutputFields: automaticOutputFields,
+    }, "standard");
     if (renderMode === "single") {
         request.outputPath = input.outputPath ?? `${stem}-product.${format}`;
         delete request.outputDir;

package/dist/quality.js

@@ -0,0 +1,24 @@
+export const QUALITY_PRESETS = {
+    preview: { width: 960, height: 540, samples: 16 },
+    standard: { width: 1920, height: 1080, samples: 64 },
+    final: { width: 3840, height: 2160, samples: 256 },
+};
+export function applyRenderQuality(input, defaultPreset) {
+    const selected = input.qualityPreset ?? defaultPreset;
+    if (!selected)
+        return { ...input };
+    const preset = QUALITY_PRESETS[selected];
+    const result = {
+        ...input,
+        qualityPreset: selected,
+        width: input.width ?? preset.width,
+        height: input.height ?? preset.height,
+    };
+    if (input.maxTimeSeconds !== undefined) {
+        delete result.samples;
+    }
+    else {
+        result.samples = input.samples ?? preset.samples;
+    }
+    return result;
+}

package/dist/result.js

@@ -10,6 +10,7 @@ export function toolResponse(result) {
     };
 }
 export function localFailure(error, extra) {
+    const guidance = classifyError(error);
     return {
         ok: false,
         data: extra?.data ?? null,
@@ -17,5 +18,81 @@ export function localFailure(error, extra) {
         warnings: extra?.warnings ?? [],
         keyshotStdoutTail: extra?.keyshotStdoutTail ?? "",
         error,
+        errorCode: extra?.errorCode ?? guidance.errorCode,
+        suggestions: extra?.suggestions ?? guidance.suggestions,
+    };
+}
+export function withErrorGuidance(result) {
+    if (result.ok || !result.error)
+        return result;
+    const guidance = classifyError(result.error);
+    return {
+        ...result,
+        errorCode: result.errorCode ?? guidance.errorCode,
+        suggestions: result.suggestions ?? guidance.suggestions,
+    };
+}
+function classifyError(error) {
+    const normalized = error.toLowerCase();
+    if (normalized.includes("headless executable not found") ||
+        (normalized.includes("path command") && normalized.includes("not found"))) {
+        return {
+            errorCode: "KEYSHOT_NOT_FOUND",
+            suggestions: ["Set KEYSHOT_HEADLESS_EXE to the full path of keyshot_headless.exe, then restart the MCP client."],
+        };
+    }
+    if (normalized.includes("license") || normalized.includes("activation")) {
+        return {
+            errorCode: "LICENSE_UNAVAILABLE",
+            suggestions: ["Open KeyShot normally and confirm that its local license is active, then retry."],
+        };
+    }
+    if (normalized.includes("could not start keyshot")) {
+        return {
+            errorCode: "KEYSHOT_START_FAILED",
+            suggestions: ["Check the KeyShot executable path and start KeyShot normally once before retrying headless mode."],
+        };
+    }
+    if (normalized.includes("timed out")) {
+        return {
+            errorCode: "KEYSHOT_TIMEOUT",
+            suggestions: ["Try the preview quality preset or increase KEYSHOT_TIMEOUT_MS for a long render."],
+        };
+    }
+    if (normalized.includes("output already exists") || normalized.includes("overwrite is false")) {
+        return {
+            errorCode: "OUTPUT_EXISTS",
+            suggestions: ["Choose another explicit output name or set overwrite=true only when replacement is intentional."],
+        };
+    }
+    if (normalized.includes("output path must stay inside")) {
+        return {
+            errorCode: "OUTPUT_OUTSIDE_ALLOWED_DIRECTORY",
+            suggestions: ["Use a path inside KEYSHOT_OUTPUT_DIR, or explicitly enable external outputs if that location is trusted."],
+        };
+    }
+    if (normalized.includes("scene file not found") ||
+        normalized.includes("model file not found") ||
+        normalized.includes("base scene file not found")) {
+        return {
+            errorCode: "INPUT_NOT_FOUND",
+            suggestions: ["Check that the input file still exists and provide its full local path."],
+        };
+    }
+    if (normalized.includes("preset not found")) {
+        return {
+            errorCode: "PRESET_NOT_FOUND",
+            suggestions: ["List the available presets first, then retry with one of the returned names."],
+        };
+    }
+    if (normalized.includes("unsupported")) {
+        return {
+            errorCode: "UNSUPPORTED_KEYSHOT_API",
+            suggestions: ["This KeyShot version does not expose the required headless API; use a supported option or verify a newer KeyShot release."],
+        };
+    }
+    return {
+        errorCode: "KEYSHOT_OPERATION_FAILED",
+        suggestions: ["Review the error and KeyShot output, then retry with simpler settings or run keyshot_status."],
     };
 }

package/dist/runner.js

@@ -2,8 +2,9 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { localFailure } from "./result.js";
+import { localFailure, withErrorGuidance } from "./result.js";
 import { normalizeOutputPaths } from "./output-paths.js";
+import { allocateAutomaticProductOutputs } from "./output-collisions.js";
 let queue = Promise.resolve();
 export function runKeyShotSerialized(config, request) {
     const run = queue.then(() => runKeyShot(config, request));
@@ -26,6 +27,9 @@ async function runKeyShot(config, request) {
     let normalizedRequest;
     try {
         normalizedRequest = await normalizeOutputPaths(config, request);
+        if (normalizedRequest.operation === "product_render") {
+            normalizedRequest = await allocateAutomaticProductOutputs(normalizedRequest);
+        }
     }
     catch (error) {
         return localFailure(errorMessage(error));
@@ -105,13 +109,13 @@ async function runKeyShot(config, request) {
         if (stderrTail)
             parsed.warnings = [...parsed.warnings, `stderr: ${stderrTail}`];
         if (processResult.exitCode !== 0 && parsed.ok) {
-            return {
+            return withErrorGuidance({
                 ...parsed,
                 ok: false,
                 error: `KeyShot exited with code ${processResult.exitCode}`,
-            };
+            });
         }
-        return parsed;
+        return withErrorGuidance(parsed);
     }
     finally {
         // Best-effort cleanup so work/tmp does not accumulate args/result files.

package/dist/schemas.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 const optionalPath = z.string().min(1).optional();
 const imageFormat = z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]);
+export const qualityPresetSchema = z.enum(["preview", "standard", "final"]);
 export const scenePathSchema = z.object({
     scenePath: z.string().min(1),
 });
@@ -16,6 +17,7 @@ export const renderSchema = z.object({
     maxTimeSeconds: z.number().positive().optional(),
     camera: z.string().min(1).optional(),
     format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
+    qualityPreset: qualityPresetSchema.optional(),
 });
 export const renderInputSchema = renderSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
     message: "Choose either samples or maxTimeSeconds, not both.",
@@ -30,6 +32,7 @@ export const batchRenderSchema = z.object({
     samples: z.number().int().positive().optional(),
     maxTimeSeconds: z.number().positive().optional(),
     format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
+    qualityPreset: qualityPresetSchema.optional(),
     overwrite: z.boolean().optional(),
 });
 export const batchRenderInputSchema = batchRenderSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
@@ -44,6 +47,7 @@ export const renderAllCamerasSchema = z.object({
     samples: z.number().int().positive().optional(),
     maxTimeSeconds: z.number().positive().optional(),
     format: imageFormat.optional(),
+    qualityPreset: qualityPresetSchema.optional(),
     overwrite: z.boolean().optional(),
     continueOnError: z.boolean().default(true),
 });
@@ -123,6 +127,7 @@ export const productRenderInputSchema = z.object({
     samples: z.number().int().positive().optional(),
     maxTimeSeconds: z.number().positive().optional(),
     format: imageFormat.optional(),
+    qualityPreset: qualityPresetSchema.optional(),
     overwrite: z.boolean().default(false),
     continueOnError: z.boolean().default(true),
 });
@@ -218,6 +223,7 @@ export const renderJobSchema = z.object({
     samples: z.number().int().positive().optional(),
     maxTimeSeconds: z.number().positive().optional(),
     format: imageFormat.optional(),
+    qualityPreset: qualityPresetSchema.optional(),
 });
 export const renderJobInputSchema = renderJobSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
     message: "Choose either samples or maxTimeSeconds, not both.",

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local MCP server for KeyShot product visualization, scene editing, camera control, and rendering.",
   "type": "module",
@@ -22,7 +22,7 @@
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "status": "node ./dist/cli/status.js",
-    "smoke:keyshot": "npm run build && node ./scripts/keyshot-smoke.mjs"
+    "smoke:keyshot": "tsc -p tsconfig.json && node ./scripts/keyshot-smoke.mjs"
   },
   "keywords": [
     "mcp",

package/scripts/keyshot-smoke.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findCameraPreset, loadCameraPresets } from "../dist/camera-presets.js";
 import { getConfig } from "../dist/config.js";
+import { runKeyShotDiagnostics } from "../dist/diagnostics.js";
 import { prepareProductRenderRequest } from "../dist/product-render.js";
 import { runKeyShotSerialized } from "../dist/runner.js";
 
@@ -37,8 +38,14 @@ async function applyStandardPreset(label, scenePath, presetName, outputScenePath
   });
 }
 
-const status = await run("1/13 KeyShot status", { operation: "status" });
-const imported = await run("2/13 Import, center, and ground generated OBJ", {
+process.stdout.write("1/14 KeyShot diagnostics... ");
+const status = await runKeyShotDiagnostics(config);
+if (!status.ok || !status.data?.ready) {
+  process.stdout.write("failed\n");
+  throw new Error(`KeyShot diagnostics: ${status.error}\n${(status.suggestions ?? []).join("\n")}`);
+}
+process.stdout.write("ok\n");
+const imported = await run("2/14 Import, center, and ground generated OBJ", {
   operation: "import_model",
   modelPath,
   outputScenePath: "demo/keyshot-mcp-demo-import.bip",
@@ -50,7 +57,7 @@ const imported = await run("2/13 Import, center, and ground generated OBJ", {
 const importedScene = imported.outputFiles[0];
 if (!importedScene) throw new Error("Import did not return a saved scene path.");
 
-const inspected = await run("3/13 Inspect imported scene", {
+const inspected = await run("3/14 Inspect imported scene", {
   operation: "inspect_scene",
   scenePath: importedScene,
 });
@@ -60,7 +67,7 @@ if (!Array.isArray(objects) || objects.length === 0) {
 }
 
 const firstCameraResult = await applyStandardPreset(
-  "4/13 Apply Front camera preset",
+  "4/14 Apply Front camera preset",
   importedScene,
   "Front",
   "demo/keyshot-mcp-demo-preset-front.bip",
@@ -68,7 +75,7 @@ const firstCameraResult = await applyStandardPreset(
 const firstCameraScene = firstCameraResult.outputFiles[0];
 if (!firstCameraScene) throw new Error("Front preset did not return a saved scene path.");
 
-const focalLengthResult = await run("5/13 Set Front camera focal length", {
+const focalLengthResult = await run("5/14 Set Front camera focal length", {
   operation: "set_camera",
   scenePath: firstCameraScene,
   cameraName: "Front",
@@ -78,7 +85,7 @@ const focalLengthResult = await run("5/13 Set Front camera focal length", {
 const focalLengthScene = focalLengthResult.outputFiles[0];
 if (!focalLengthScene) throw new Error("Focal-length update did not return a saved scene path.");
 
-const environmentResult = await run("6/13 Rotate the active environment", {
+const environmentResult = await run("6/14 Rotate the active environment", {
   operation: "set_environment",
   scenePath: focalLengthScene,
   rotation: 45,
@@ -88,7 +95,7 @@ const environmentScene = environmentResult.outputFiles[0];
 if (!environmentScene) throw new Error("Environment update did not return a saved scene path.");
 
 const secondCameraResult = await applyStandardPreset(
-  "7/13 Apply Isometric camera preset",
+  "7/14 Apply Isometric camera preset",
   environmentScene,
   "Isometric",
   "demo/keyshot-mcp-demo-presets.bip",
@@ -96,7 +103,7 @@ const secondCameraResult = await applyStandardPreset(
 const cameraScene = secondCameraResult.outputFiles[0];
 if (!cameraScene) throw new Error("Isometric preset did not return a saved scene path.");
 
-const fieldOfViewResult = await run("8/13 Set Isometric camera field of view and distance", {
+const fieldOfViewResult = await run("8/14 Set Isometric camera field of view and distance", {
   operation: "set_camera",
   scenePath: cameraScene,
   cameraName: "Isometric",
@@ -107,7 +114,7 @@ const fieldOfViewResult = await run("8/13 Set Isometric camera field of view and
 const productCameraScene = fieldOfViewResult.outputFiles[0];
 if (!productCameraScene) throw new Error("Field-of-view update did not return a saved scene path.");
 
-const rendered = await run("9/13 Discover and render every camera", {
+const rendered = await run("9/14 Discover and render every camera", {
   operation: "render_all_cameras",
   scenePath: productCameraScene,
   outputDir: "demo/all-cameras",
@@ -140,26 +147,35 @@ const minimumSizes = await Promise.all(namedResults.map(async (entry) => (await
 if (minimumSizes.some((size) => size < 10000)) {
   throw new Error("A demo camera render is unexpectedly small and may be blank.");
 }
-process.stdout.write("10/13 Verify two different camera images... ok\n");
-process.stdout.write("11/13 Verify composition, lens, and environment operations... ok\n");
+process.stdout.write("10/14 Verify two different camera images... ok\n");
+process.stdout.write("11/14 Verify composition, lens, and environment operations... ok\n");
 
 const oneClickModelRequest = await prepareProductRenderRequest(config, {
   modelPath,
-  outputScenePath: "demo/one-click-cube.bip",
-  outputPath: "demo/one-click-cube.png",
   renderMode: "single",
-  width: 640,
-  height: 480,
-  maxTimeSeconds: 8,
+  qualityPreset: "standard",
   format: "png",
-  overwrite: true,
+  overwrite: false,
   continueOnError: true,
 });
-const oneClickModel = await run("12/13 One-click model-to-product render", oneClickModelRequest);
+const oneClickModel = await run("12/14 Standard-quality one-click product render", oneClickModelRequest);
 if (!oneClickModel.data?.savedScene || oneClickModel.data?.renders?.length !== 1) {
   throw new Error("One-click model workflow did not return a scene and one render.");
 }
 
+const repeatedRequest = await prepareProductRenderRequest(config, {
+  modelPath,
+  renderMode: "single",
+  qualityPreset: "preview",
+  format: "png",
+  overwrite: false,
+  continueOnError: true,
+});
+const repeatedModel = await run("13/14 Repeated preview render with automatic numbering", repeatedRequest);
+if (!repeatedModel.data?.savedScene || repeatedModel.data?.savedScene === oneClickModel.data.savedScene) {
+  throw new Error("Repeated one-click render did not allocate a new numbered scene path.");
+}
+
 const oneClickSceneRequest = await prepareProductRenderRequest(config, {
   scenePath: productCameraScene,
   outputScenePath: "demo/one-click-existing-scene.bip",
@@ -172,7 +188,7 @@ const oneClickSceneRequest = await prepareProductRenderRequest(config, {
   overwrite: true,
   continueOnError: true,
 });
-const oneClickScene = await run("13/13 One-click existing-scene all-camera render", oneClickSceneRequest);
+const oneClickScene = await run("14/14 One-click existing-scene all-camera render", oneClickSceneRequest);
 if (!oneClickScene.data?.savedScene || oneClickScene.data?.renders?.length < 2) {
   throw new Error("One-click scene workflow did not preserve the scene and render all cameras.");
 }
@@ -183,7 +199,9 @@ console.log(JSON.stringify({
   scenePath: productCameraScene,
   cameraCount: renderData.total,
   renderedImages: rendered.outputFiles,
-  oneClickOutputs: [...oneClickModel.outputFiles, ...oneClickScene.outputFiles],
+  oneClickOutputs: [...oneClickModel.outputFiles, ...repeatedModel.outputFiles, ...oneClickScene.outputFiles],
+  diagnosticChecks: status.data?.checks ?? [],
+  verifiedQualities: ["standard", "preview"],
   verifiedPresets: namedResults.map((entry) => entry.camera),
   verifiedControls: {
     importOptions: ["centerGeometry", "snapToGround", "adjustCameraLookAt", "adjustEnvironment"],

package/scripts/keyshot_bridge.py

@@ -181,6 +181,7 @@ def render(payload, output_files, warnings):
         "height": height,
         "samples": samples,
         "maxTimeSeconds": max_time,
+        "qualityPreset": payload.get("qualityPreset"),
     }
 
 

package/server.json

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