keyshot-mcp 0.0.0 → 0.2.1

package/dist/runner.js

@@ -0,0 +1,134 @@
+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";
+let queue = Promise.resolve();
+export function runKeyShotSerialized(config, request) {
+    const run = queue.then(() => runKeyShot(config, request));
+    queue = run.catch(() => undefined);
+    return run;
+}
+async function runKeyShot(config, request) {
+    const exeExists = await exists(config.keyshotHeadlessExe);
+    if (!exeExists) {
+        return localFailure(`KeyShot headless executable not found: ${config.keyshotHeadlessExe}`);
+    }
+    const bridgeExists = await exists(config.bridgeScriptPath);
+    if (!bridgeExists) {
+        return localFailure(`KeyShot bridge script not found: ${config.bridgeScriptPath}`);
+    }
+    if (request.scenePath && !(await exists(request.scenePath))) {
+        return localFailure(`Scene file not found: ${request.scenePath}`);
+    }
+    await fs.mkdir(config.tmpDir, { recursive: true });
+    await fs.mkdir(config.keyshotOutputDir, { recursive: true });
+    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,
+        defaults: {
+            outputDir: config.keyshotOutputDir,
+        },
+    };
+    await fs.writeFile(argsPath, JSON.stringify(payload, null, 2), "utf8");
+    const args = [
+        ...config.keyshotLicenseArgs,
+        "-progress",
+        ...(request.scenePath ? [request.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"));
+        }
+        catch (error) {
+            return localFailure(`Could not parse KeyShot result JSON: ${errorMessage(error)}`, {
+                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;
+}
+function spawnWithTimeout(command, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!settled)
+                    child.kill("SIGKILL");
+            }, 2500).unref();
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (error) => {
+            stderr += errorMessage(error);
+        });
+        child.on("close", (exitCode) => {
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode, stdout, stderr, timedOut });
+        });
+    });
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tail(value, maxChars) {
+    return value.length <= maxChars ? value : value.slice(value.length - maxChars);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/schemas.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+const optionalPath = z.string().min(1).optional();
+export const scenePathSchema = z.object({
+    scenePath: z.string().min(1),
+});
+export const renderSchema = z.object({
+    scenePath: z.string().min(1),
+    outputPath: optionalPath,
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    samples: z.number().int().positive().optional(),
+    maxTimeSeconds: z.number().positive().optional(),
+    camera: z.string().min(1).optional(),
+    format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
+});
+export const batchRenderSchema = z.object({
+    scenePath: z.string().min(1),
+    outputDir: z.string().min(1),
+    cameras: z.array(z.string().min(1)).min(1),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    samples: z.number().int().positive().optional(),
+    maxTimeSeconds: z.number().positive().optional(),
+    format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
+    overwrite: z.boolean().optional(),
+});
+export const importModelSchema = z.object({
+    modelPath: z.string().min(1),
+    baseScenePath: optionalPath,
+    outputScenePath: z.string().min(1),
+});
+export const applyMaterialInputSchema = z.object({
+    scenePath: z.string().min(1),
+    objectName: z.string().min(1).optional(),
+    objectPath: z.string().min(1).optional(),
+    materialName: z.string().min(1).optional(),
+    materialPath: z.string().min(1).optional(),
+    outputScenePath: z.string().min(1),
+});
+export const applyMaterialSchema = applyMaterialInputSchema.refine((value) => value.objectName || value.objectPath, {
+    message: "Provide objectName or objectPath.",
+}).refine((value) => value.materialName || value.materialPath, {
+    message: "Provide materialName or materialPath.",
+});
+const vector3 = z.tuple([z.number(), z.number(), z.number()]);
+export const setCameraSchema = z.object({
+    scenePath: z.string().min(1),
+    cameraName: z.string().min(1).optional(),
+    position: vector3,
+    lookAt: vector3,
+    up: vector3.optional(),
+    distance: z.number().positive().optional(),
+    outputScenePath: z.string().min(1),
+});
+export const setEnvironmentSchema = z.object({
+    scenePath: z.string().min(1),
+    environmentName: z.string().min(1).optional(),
+    environmentPath: z.string().min(1).optional(),
+    brightness: z.number().positive().optional(),
+    outputScenePath: z.string().min(1),
+});
+export const saveSceneSchema = z.object({
+    scenePath: z.string().min(1),
+    outputScenePath: z.string().min(1),
+});

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/examples/claude-desktop.example.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "keyshot": {
+      "command": "node",
+      "args": [
+        "C:/path/to/keyshot-mcp/dist/index.js"
+      ],
+      "env": {
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
+      }
+    }
+  }
+}

package/examples/codex.example.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "keyshot": {
+      "command": "node",
+      "args": [
+        "C:/path/to/keyshot-mcp/dist/index.js"
+      ],
+      "env": {
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe",
+        "KEYSHOT_TIMEOUT_MS": "600000"
+      }
+    }
+  }
+}

package/examples/mcp-client.example.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "keyshot": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/keyshot-mcp/dist/index.js"
+      ],
+      "env": {
+        "KEYSHOT_HEADLESS_EXE": "/absolute/path/to/keyshot_headless"
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,53 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.0.0",
-  "description": "Placeholder package for configuring npm trusted publishing. The real package is published from GitHub Actions.",
+  "version": "0.2.1",
+  "description": "Local and portable MCP server for KeyShot headless scripting.",
+  "type": "module",
+  "homepage": "https://github.com/truman-t3/keyshot-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/truman-t3/keyshot-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/truman-t3/keyshot-mcp/issues"
+  },
+  "bin": {
+    "keyshot-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "start": "node ./dist/index.js",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "status": "node ./dist/cli/status.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "keyshot",
+    "rendering",
+    "keyshot-studio",
+    "stdio"
+  ],
+  "files": [
+    "dist",
+    "scripts/keyshot_bridge.py",
+    "examples",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
   "license": "MIT",
-  "private": false
-}
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.17.2",
+    "typescript": "^5.9.2"
+  }
+}