keyshot-mcp 0.2.1 → 0.4.2

package/dist/runner.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { localFailure } from "./result.js";
+import { normalizeOutputPaths } from "./output-paths.js";
 let queue = Promise.resolve();
 export function runKeyShotSerialized(config, request) {
     const run = queue.then(() => runKeyShot(config, request));
@@ -10,8 +11,7 @@ export function runKeyShotSerialized(config, request) {
     return run;
 }
 async function runKeyShot(config, request) {
-    const exeExists = await exists(config.keyshotHeadlessExe);
-    if (!exeExists) {
+    if (isPathLike(config.keyshotHeadlessExe) && !(await exists(config.keyshotHeadlessExe))) {
         return localFailure(`KeyShot headless executable not found: ${config.keyshotHeadlessExe}`);
     }
     const bridgeExists = await exists(config.bridgeScriptPath);
@@ -23,11 +23,18 @@ async function runKeyShot(config, request) {
     }
     await fs.mkdir(config.tmpDir, { recursive: true });
     await fs.mkdir(config.keyshotOutputDir, { recursive: true });
+    let normalizedRequest;
+    try {
+        normalizedRequest = await normalizeOutputPaths(config, request);
+    }
+    catch (error) {
+        return localFailure(errorMessage(error));
+    }
     const id = `${Date.now()}-${randomUUID()}`;
     const argsPath = path.join(config.tmpDir, `${id}.args.json`);
     const resultPath = path.join(config.tmpDir, `${id}.result.json`);
     const payload = {
-        ...request,
+        ...normalizedRequest,
         defaults: {
             outputDir: config.keyshotOutputDir,
         },
@@ -36,56 +43,77 @@ async function runKeyShot(config, request) {
     const args = [
         ...config.keyshotLicenseArgs,
         "-progress",
-        ...(request.scenePath ? [request.scenePath] : []),
+        ...(normalizedRequest.scenePath ? [normalizedRequest.scenePath] : []),
         "-script",
         config.bridgeScriptPath,
         argsPath,
         resultPath,
     ];
-    const processResult = await spawnWithTimeout(config.keyshotHeadlessExe, args, config.keyshotTimeoutMs);
-    const stdoutTail = tail(processResult.stdout, 6000);
-    const stderrTail = tail(processResult.stderr, 6000);
-    let parsed = null;
-    if (await exists(resultPath)) {
-        try {
-            parsed = JSON.parse(await fs.readFile(resultPath, "utf8"));
+    try {
+        const processResult = await spawnWithTimeout(config.keyshotHeadlessExe, args, config.keyshotTimeoutMs);
+        const stdoutTail = tail(processResult.stdout, 6000);
+        const stderrTail = tail(processResult.stderr, 6000);
+        let parsed = null;
+        if (await exists(resultPath)) {
+            try {
+                parsed = JSON.parse(await fs.readFile(resultPath, "utf8"));
+            }
+            catch (error) {
+                return localFailure(`Could not parse KeyShot result JSON: ${errorMessage(error)}`, {
+                    keyshotStdoutTail: stdoutTail,
+                    warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
+                });
+            }
         }
-        catch (error) {
-            return localFailure(`Could not parse KeyShot result JSON: ${errorMessage(error)}`, {
+        if (processResult.spawnError) {
+            return localFailure(`Could not start KeyShot headless: ${processResult.spawnError}`, {
                 keyshotStdoutTail: stdoutTail,
                 warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
             });
         }
+        if (processResult.timedOut) {
+            return localFailure(`KeyShot timed out after ${config.keyshotTimeoutMs}ms`, {
+                data: parsed?.data ?? null,
+                outputFiles: parsed?.outputFiles ?? [],
+                warnings: [...(parsed?.warnings ?? []), ...(stderrTail ? [`stderr: ${stderrTail}`] : [])],
+                keyshotStdoutTail: stdoutTail,
+            });
+        }
+        if (!parsed) {
+            return localFailure(`KeyShot did not produce a result file. Exit code: ${processResult.exitCode ?? "unknown"}`, {
+                keyshotStdoutTail: stdoutTail,
+                warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
+            });
+        }
+        parsed.keyshotStdoutTail = stdoutTail || parsed.keyshotStdoutTail || "";
+        if (stderrTail)
+            parsed.warnings = [...parsed.warnings, `stderr: ${stderrTail}`];
+        if (processResult.exitCode !== 0 && parsed.ok) {
+            return {
+                ...parsed,
+                ok: false,
+                error: `KeyShot exited with code ${processResult.exitCode}`,
+            };
+        }
+        return parsed;
     }
-    if (processResult.timedOut) {
-        return localFailure(`KeyShot timed out after ${config.keyshotTimeoutMs}ms`, {
-            data: parsed?.data ?? null,
-            outputFiles: parsed?.outputFiles ?? [],
-            warnings: [...(parsed?.warnings ?? []), ...(stderrTail ? [`stderr: ${stderrTail}`] : [])],
-            keyshotStdoutTail: stdoutTail,
-        });
-    }
-    if (!parsed) {
-        return localFailure(`KeyShot did not produce a result file. Exit code: ${processResult.exitCode ?? "unknown"}`, {
-            keyshotStdoutTail: stdoutTail,
-            warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
-        });
-    }
-    parsed.keyshotStdoutTail = stdoutTail || parsed.keyshotStdoutTail || "";
-    if (stderrTail)
-        parsed.warnings = [...parsed.warnings, `stderr: ${stderrTail}`];
-    if (processResult.exitCode !== 0 && parsed.ok) {
-        return {
-            ...parsed,
-            ok: false,
-            error: `KeyShot exited with code ${processResult.exitCode}`,
-        };
+    finally {
+        // Best-effort cleanup so work/tmp does not accumulate args/result files.
+        await cleanupTmp([argsPath, resultPath]).catch(() => undefined);
     }
-    return parsed;
 }
-function spawnWithTimeout(command, args, timeoutMs) {
+async function cleanupTmp(paths) {
+    await Promise.all(paths.map(async (filePath) => {
+        if (await exists(filePath)) {
+            await fs.rm(filePath, { force: true });
+        }
+    }));
+}
+export const MAX_CAPTURE_CHARS = 64 * 1024;
+export function spawnWithTimeout(command, args, timeoutMs) {
     return new Promise((resolve) => {
         const child = spawn(command, args, {
+            detached: process.platform !== "win32",
             windowsHide: true,
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -93,30 +121,64 @@ function spawnWithTimeout(command, args, timeoutMs) {
         let stderr = "";
         let settled = false;
         let timedOut = false;
+        let spawnError = null;
         const timer = setTimeout(() => {
             timedOut = true;
-            child.kill("SIGTERM");
+            terminateProcessTree(child.pid, "SIGTERM");
             setTimeout(() => {
-                if (!settled)
-                    child.kill("SIGKILL");
+                if (!settled && process.platform !== "win32")
+                    terminateProcessTree(child.pid, "SIGKILL");
             }, 2500).unref();
         }, timeoutMs);
         child.stdout?.on("data", (chunk) => {
-            stdout += String(chunk);
+            stdout = appendBounded(stdout, String(chunk));
         });
         child.stderr?.on("data", (chunk) => {
-            stderr += String(chunk);
+            stderr = appendBounded(stderr, String(chunk));
         });
         child.on("error", (error) => {
-            stderr += errorMessage(error);
+            spawnError = errorMessage(error);
+            stderr = appendBounded(stderr, spawnError);
         });
         child.on("close", (exitCode) => {
             settled = true;
             clearTimeout(timer);
-            resolve({ exitCode, stdout, stderr, timedOut });
+            resolve({ exitCode, stdout, stderr, timedOut, spawnError });
         });
     });
 }
+function terminateProcessTree(pid, signal) {
+    if (!pid)
+        return;
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        killer.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // The process may already have exited.
+        }
+    }
+}
+function appendBounded(current, addition) {
+    const combined = current + addition;
+    return combined.length <= MAX_CAPTURE_CHARS
+        ? combined
+        : combined.slice(combined.length - MAX_CAPTURE_CHARS);
+}
+function isPathLike(command) {
+    return path.isAbsolute(command) || command.includes("/") || command.includes("\\");
+}
 async function exists(filePath) {
     try {
         await fs.access(filePath);

package/dist/schemas.js

@@ -1,8 +1,12 @@
 import { z } from "zod";
 const optionalPath = z.string().min(1).optional();
+const imageFormat = z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]);
 export const scenePathSchema = z.object({
     scenePath: z.string().min(1),
 });
+export const listCamerasSchema = z.object({
+    scenePath: z.string().min(1),
+});
 export const renderSchema = z.object({
     scenePath: z.string().min(1),
     outputPath: optionalPath,
@@ -13,6 +17,10 @@ export const renderSchema = z.object({
     camera: z.string().min(1).optional(),
     format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
 });
+export const renderInputSchema = renderSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
+    message: "Choose either samples or maxTimeSeconds, not both.",
+    path: ["maxTimeSeconds"],
+});
 export const batchRenderSchema = z.object({
     scenePath: z.string().min(1),
     outputDir: z.string().min(1),
@@ -24,6 +32,10 @@ export const batchRenderSchema = z.object({
     format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
     overwrite: z.boolean().optional(),
 });
+export const batchRenderInputSchema = batchRenderSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
+    message: "Choose either samples or maxTimeSeconds, not both.",
+    path: ["maxTimeSeconds"],
+});
 export const importModelSchema = z.object({
     modelPath: z.string().min(1),
     baseScenePath: optionalPath,
@@ -63,3 +75,36 @@ export const saveSceneSchema = z.object({
     scenePath: z.string().min(1),
     outputScenePath: z.string().min(1),
 });
+// --- Render queue ---
+export const renderJobSchema = z.object({
+    scenePath: z.string().min(1),
+    outputPath: optionalPath,
+    camera: z.string().min(1).optional(),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    samples: z.number().int().positive().optional(),
+    maxTimeSeconds: z.number().positive().optional(),
+    format: imageFormat.optional(),
+});
+export const renderJobInputSchema = renderJobSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
+    message: "Choose either samples or maxTimeSeconds, not both.",
+    path: ["maxTimeSeconds"],
+});
+export const renderQueueSchema = z.object({
+    jobs: z.array(renderJobSchema).min(1),
+    continueOnError: z.boolean().optional(),
+});
+export const renderQueueInputSchema = z.object({
+    jobs: z.array(renderJobInputSchema).min(1),
+    continueOnError: z.boolean().optional(),
+});
+// --- Material preset library ---
+export const listMaterialPresetsSchema = z.object({});
+export const applyMaterialPresetInputSchema = z.object({
+    scenePath: z.string().min(1),
+    presetName: z.string().min(1),
+    objectName: z.string().min(1).optional(),
+    objectPath: z.string().min(1).optional(),
+    outputScenePath: z.string().min(1),
+});
+export const applyMaterialPresetSchema = applyMaterialPresetInputSchema.refine((value) => value.objectName || value.objectPath, { message: "Provide objectName or objectPath." });

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.4.2";

package/examples/demo/README.md

@@ -0,0 +1,9 @@
+# KeyShot smoke-test demo
+
+`keyshot-mcp-cube.obj` is original, generated geometry included under this
+repository's MIT license. It contains no customer model or third-party asset.
+
+Run `npm run smoke:keyshot` after setting `KEYSHOT_HEADLESS_EXE`. The command
+checks KeyShot, imports the cube, saves and inspects the scene, creates an MCP
+camera, and renders `outputs/demo/keyshot-mcp-demo.png`. Generated `.bip` files
+remain under `outputs/` and are ignored by Git.

package/examples/demo/keyshot-mcp-cube.obj

@@ -0,0 +1,23 @@
+# KeyShot MCP generated demo cube
+# Original geometry released under the repository MIT license.
+o KeyShot_MCP_Cube
+v -1.0 -1.0 -1.0
+v  1.0 -1.0 -1.0
+v  1.0  1.0 -1.0
+v -1.0  1.0 -1.0
+v -1.0 -1.0  1.0
+v  1.0 -1.0  1.0
+v  1.0  1.0  1.0
+v -1.0  1.0  1.0
+vn  0.0  0.0 -1.0
+vn  0.0  0.0  1.0
+vn  0.0 -1.0  0.0
+vn  0.0  1.0  0.0
+vn -1.0  0.0  0.0
+vn  1.0  0.0  0.0
+f 1//1 4//1 3//1 2//1
+f 5//2 6//2 7//2 8//2
+f 1//3 2//3 6//3 5//3
+f 4//4 8//4 7//4 3//4
+f 1//5 5//5 8//5 4//5
+f 2//6 3//6 7//6 6//6

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.2.1",
+  "version": "0.4.2",
+  "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local and portable MCP server for KeyShot headless scripting.",
   "type": "module",
   "homepage": "https://github.com/truman-t3/keyshot-mcp#readme",
@@ -19,7 +20,9 @@
     "prepare": "tsc -p tsconfig.json",
     "start": "node ./dist/index.js",
     "check": "tsc -p tsconfig.json --noEmit",
-    "status": "node ./dist/cli/status.js"
+    "test": "vitest run",
+    "status": "node ./dist/cli/status.js",
+    "smoke:keyshot": "npm run build && node ./scripts/keyshot-smoke.mjs"
   },
   "keywords": [
     "mcp",
@@ -32,7 +35,11 @@
   "files": [
     "dist",
     "scripts/keyshot_bridge.py",
+    "scripts/keyshot-smoke.mjs",
     "examples",
+    "assets/demo",
+    "presets",
+    "server.json",
     "README.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -42,12 +49,14 @@
   "engines": {
     "node": ">=20"
   },
+  "packageManager": "pnpm@10.17.1",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.18.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.17.2",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   }
 }

package/presets/materials.json

@@ -0,0 +1,14 @@
+{
+  "Brushed Steel": {
+    "materialName": "Steel Brushed",
+    "description": "Default brushed stainless steel look for metal parts."
+  },
+  "Matte Black Plastic": {
+    "materialName": "Plastic Matte Black",
+    "description": "Soft-touch matte black plastic for housings and enclosures."
+  },
+  "Clear Glass": {
+    "materialName": "Glass Clear",
+    "description": "Transparent glass for covers and lenses."
+  }
+}

package/scripts/keyshot-smoke.mjs

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getConfig } from "../dist/config.js";
+import { runKeyShotSerialized } from "../dist/runner.js";
+
+const repoRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const config = getConfig();
+const modelPath = path.join(repoRoot, "examples", "demo", "keyshot-mcp-cube.obj");
+
+async function run(label, request) {
+  process.stdout.write(`${label}... `);
+  const result = await runKeyShotSerialized(config, request);
+  if (!result.ok) {
+    process.stdout.write("failed\n");
+    throw new Error(`${label}: ${result.error}\n${result.warnings.join("\n")}`);
+  }
+  process.stdout.write("ok\n");
+  return result;
+}
+
+const status = await run("1/5 KeyShot status", { operation: "status" });
+const imported = await run("2/5 Import and save generated OBJ", {
+  operation: "import_model",
+  modelPath,
+  outputScenePath: "demo/keyshot-mcp-demo-import.bip",
+});
+const importedScene = imported.outputFiles[0];
+if (!importedScene) throw new Error("Import did not return a saved scene path.");
+
+const inspected = await run("3/5 Inspect imported scene", {
+  operation: "inspect_scene",
+  scenePath: importedScene,
+});
+const objects = inspected.data?.objects;
+if (!Array.isArray(objects) || objects.length === 0) {
+  throw new Error("Imported scene did not contain any inspectable objects.");
+}
+
+const cameraSceneResult = await run("4/5 Create camera and save scene", {
+  operation: "set_camera",
+  scenePath: importedScene,
+  cameraName: "MCP Demo",
+  position: [4.5, 3.5, 4.5],
+  lookAt: [0, 0, 0],
+  up: [0, 1, 0],
+  outputScenePath: "demo/keyshot-mcp-demo-camera.bip",
+});
+const cameraScene = cameraSceneResult.outputFiles[0];
+if (!cameraScene) throw new Error("Camera operation did not return a saved scene path.");
+
+const rendered = await run("5/5 Render real PNG", {
+  operation: "render",
+  scenePath: cameraScene,
+  camera: "MCP Demo",
+  outputPath: "demo/keyshot-mcp-demo.png",
+  width: 640,
+  height: 480,
+  maxTimeSeconds: 8,
+  format: "png",
+});
+
+console.log(JSON.stringify({
+  keyshotVersion: status.data?.version ?? null,
+  objectCount: objects.length,
+  scenePath: cameraScene,
+  imagePath: rendered.outputFiles[0] ?? null,
+}, null, 2));