keyshot-mcp 0.4.2 → 0.6.0

package/README.md

@@ -28,9 +28,11 @@ This project does not include KeyShot, does not bypass licensing, and does not s
 - Inspect a `.bip` or supported KeyShot scene file.
 - Render a scene to an image.
 - Batch render multiple named cameras from one scene.
+- Automatically discover and render every camera in one scene.
 - Import a model into a scene.
 - Apply a material to an object.
 - Create or update a camera.
+- Apply reusable standard or custom camera presets.
 - Set an environment when the installed KeyShot version exposes that function.
 - Save a scene to a new file.
 
@@ -67,7 +69,7 @@ This project does not include KeyShot, does not bypass licensing, and does not s
 npm install -g keyshot-mcp
 ```
 
-The current release line is `0.4.2`. The published package is the easiest option
+The current release line is `0.6.0`. The published package is the easiest option
 when you only want to use the MCP server. You still need KeyShot Studio and a
 local KeyShot license.
 
@@ -91,7 +93,7 @@ Use exactly one of these approaches:
 **No installation, run with npx**:
 
 ```json
-{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.4.2"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.6.0"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
 ```
 
 **Run from a cloned source directory** (after `npm install && npm run build`):
@@ -105,11 +107,11 @@ Use exactly one of these approaches:
 If you use Codex or another coding agent, you can copy this prompt and let the agent install the MCP server for you:
 
 ```text
-Install KeyShot MCP 0.4.2 from npm and configure it in my MCP client.
+Install KeyShot MCP 0.6.0 from npm and configure it in my MCP client.
 
 Please:
 1. Find my KeyShot headless executable path.
-2. Add a keyshot MCP server using npx -y keyshot-mcp@0.4.2.
+2. Add a keyshot MCP server using npx -y keyshot-mcp@0.6.0.
 3. Set KEYSHOT_HEADLESS_EXE to the detected keyshot_headless path.
 4. Test the setup by running the keyshot_status tool.
 5. Tell me the exact config that was added and whether the status check passed.
@@ -202,6 +204,16 @@ List the cameras in this KeyShot scene, create or update a camera named "Hero",
 save the scene to a new file, and render one preview from that camera.
 ```
 
+```text
+Find every camera in this KeyShot scene and render all views to the all-cameras
+output folder. Continue if one camera fails and report the result for each view.
+```
+
+```text
+List the available camera presets, apply the Isometric preset as a camera named
+"Catalog Isometric", save a new scene, and render a preview from that camera.
+```
+
 ## Environment Variables
 
 - `KEYSHOT_HEADLESS_EXE`: path to `keyshot_headless` or `keyshot_headless.exe`.
@@ -209,6 +221,7 @@ save the scene to a new file, and render one preview from that camera.
 - `KEYSHOT_LICENSE_ARGS`: optional KeyShot headless license arguments. Empty by default.
 - `KEYSHOT_TIMEOUT_MS`: operation timeout in milliseconds. Default: `600000`.
 - `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS`: allow output paths outside `KEYSHOT_OUTPUT_DIR`. Default: `false`.
+- `KEYSHOT_CAMERA_PRESETS`: camera preset JSON file. Default: `presets/cameras.json`.
 
 By default every output file must stay inside `KEYSHOT_OUTPUT_DIR`. Relative paths
 are placed there automatically. Set the compatibility switch to `true` only when
@@ -224,15 +237,27 @@ or the other, not both.
 - `keyshot_list_cameras`: list available camera names in a scene (handy before batch rendering)
 - `keyshot_render`: render a single image
 - `keyshot_batch_render`
+- `keyshot_render_all_cameras`: discover and render every camera in a scene; continues after individual failures by default
 - `keyshot_render_queue`: run several render jobs sequentially (stops at first failure unless `continueOnError`)
 - `keyshot_import_model`
 - `keyshot_apply_material`
 - `keyshot_list_material_presets`: list presets from the material preset library
 - `keyshot_apply_material_preset`: apply a named preset from the library to an object
 - `keyshot_set_camera`
+- `keyshot_list_camera_presets`: list standard and custom camera presets
+- `keyshot_apply_camera_preset`: create or update a named camera from a preset
 - `keyshot_set_environment`
 - `keyshot_save_scene`
 
+### Render every camera automatically
+
+`keyshot_render_all_cameras` discovers camera names from the open scene and renders
+them in one KeyShot headless session. `continueOnError` defaults to `true`, so a
+failed camera is reported without blocking the remaining views. Safe duplicate
+filenames receive `-2`, `-3`, and later suffixes. Existing files are preserved
+unless `overwrite` is set to `true`. KeyShot's internal, non-activatable
+`last_active` placeholder is reported and skipped.
+
 ### Material preset library
 
 `keyshot_apply_material_preset` reads a small JSON registry so you can reuse named
@@ -249,6 +274,30 @@ looks instead of remembering exact KeyShot material names. Default location:
 Each preset must have a `materialName` or a `materialPath`. Use
 `keyshot_list_material_presets` to see what is available.
 
+### Camera preset library
+
+The built-in `presets/cameras.json` provides Front, Back, Left, Right, Top,
+Bottom, and Isometric standard views. Use `keyshot_list_camera_presets` to list
+them and `keyshot_apply_camera_preset` to create or update a named camera.
+
+Set `KEYSHOT_CAMERA_PRESETS` to a user-managed JSON file for custom presets:
+
+```json
+{
+  "Front": { "standardView": "front" },
+  "Hero": {
+    "position": [4.5, 3.5, 4.5],
+    "lookAt": [0, 0, 0],
+    "up": [0, 1, 0],
+    "description": "Custom absolute product camera"
+  }
+}
+```
+
+A preset file may use the object format shown above or an array whose entries
+include a `name`. Each preset must contain either one supported `standardView`,
+or both `position` and `lookAt`. Preset files are read-only to this MCP server.
+
 ## MCP Prompts and Resources
 
 - Prompt: `keyshot_product_render`
@@ -269,9 +318,9 @@ KeyShot's Python `lux` API changes across versions. This server keeps the MCP in
 
 ## Roadmap
 
-- [ ] Auto-discover and batch render all cameras in a scene
+- [x] Auto-discover and batch render all cameras in a scene
 - [x] Material preset library
-- [ ] Camera preset templates
+- [x] Camera preset templates
 - [x] Sequential render queue
 - [x] Safer output directory restrictions
 - [ ] More tested KeyShot versions
@@ -283,7 +332,7 @@ KeyShot's Python `lux` API changes across versions. This server keeps the MCP in
 ![KeyShot MCP generated cube demo](assets/demo/keyshot-mcp-demo.png)
 
 The demo uses only the generated geometry in `examples/demo`. To reproduce the
-status, import, inspect, camera, save, and PNG-render workflow locally:
+status, import, inspect, two-camera creation, save, discovery, and PNG-render workflow locally:
 
 ```bash
 npm run smoke:keyshot
@@ -321,9 +370,11 @@ MIT
 - 检查 `.bip` 或 KeyShot 支持的场景文件。
 - 把场景渲染成图片。
 - 从同一个场景批量渲染多个指定相机。
+- 自动发现并渲染场景中的全部相机。
 - 把模型导入场景。
 - 给对象替换材质。
 - 创建或更新相机。
+- 应用可复用的标准或自定义相机预设。
 - 在当前 KeyShot 版本支持时设置环境。
 - 把场景保存为新文件。
 
@@ -360,7 +411,7 @@ MIT
 npm install -g keyshot-mcp
 ```
 
-当前发布版本为 `0.4.2`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
+当前发布版本为 `0.6.0`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
 电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
 
 ### 从源码安装
@@ -383,7 +434,7 @@ npm run build
 **免安装，直接使用 npx**：
 
 ```json
-{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.4.2"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.6.0"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
 ```
 
 **使用本地源码**（先运行 `npm install && npm run build`）：
@@ -397,11 +448,11 @@ npm run build
 如果你使用 Codex 或其他编程 Agent，可以复制下面这段话，让 Agent 帮你安装和配置 MCP：
 
 ```text
-请帮我安装 KeyShot MCP 0.4.2，并添加到我的 MCP 客户端。
+请帮我安装 KeyShot MCP 0.6.0，并添加到我的 MCP 客户端。
 
 请你：
 1. 查找我电脑上的 KeyShot headless 可执行文件路径。
-2. 使用 npx -y keyshot-mcp@0.4.2 添加 keyshot MCP server。
+2. 使用 npx -y keyshot-mcp@0.6.0 添加 keyshot MCP server。
 3. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
 4. 用 keyshot_status 工具测试是否配置成功。
 5. 最后告诉我实际添加的配置，以及状态检查是否通过。
@@ -494,6 +545,16 @@ examples/codex.example.json
 把场景保存为新文件，并用这个相机渲染一张预览图。
 ```
 
+```text
+自动找出这个 KeyShot 场景里的全部相机，把所有视角渲染到 all-cameras 文件夹。
+某个相机失败时继续处理其他相机，最后告诉我每个视角的结果。
+```
+
+```text
+列出可用的相机预设，把 Isometric 等距预设应用为名为“目录等距视图”的相机，
+保存一份新场景，并用这个相机渲染预览图。
+```
+
 ## 环境变量
 
 - `KEYSHOT_HEADLESS_EXE`：`keyshot_headless` 或 `keyshot_headless.exe` 的路径。
@@ -502,6 +563,7 @@ examples/codex.example.json
 - `KEYSHOT_TIMEOUT_MS`：单次操作超时时间，单位毫秒，默认 `600000`。
 - `KEYSHOT_MATERIAL_PRESETS`：材质预设库 JSON 文件路径，默认 `presets/materials.json`。
 - `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS`：是否允许写到默认输出目录之外，默认 `false`。
+- `KEYSHOT_CAMERA_PRESETS`：相机预设 JSON 文件路径，默认 `presets/cameras.json`。
 
 默认情况下，所有输出图片和场景都必须写入 `KEYSHOT_OUTPUT_DIR`，相对路径会自动放入该目录。
 只有确实需要写到外部目录时才设置为 `true`；输入场景和模型路径不受此限制。
@@ -515,15 +577,25 @@ examples/codex.example.json
 - `keyshot_list_cameras`：列出场景中所有相机名称（批量渲染前很有用）。
 - `keyshot_render`：渲染单张图片。
 - `keyshot_batch_render`：批量渲染多个相机视角。
+- `keyshot_render_all_cameras`：自动发现并渲染场景中的全部相机，默认单个视角失败后继续。
 - `keyshot_render_queue`：顺序执行多个渲染任务（默认遇错即停，设置 `continueOnError` 可继续）。
 - `keyshot_import_model`：导入模型。
 - `keyshot_apply_material`：替换材质。
 - `keyshot_list_material_presets`：列出材质预设库中的预设。
 - `keyshot_apply_material_preset`：把预设库中的某个命名材质应用到物体上。
 - `keyshot_set_camera`：设置相机。
+- `keyshot_list_camera_presets`：列出标准和自定义相机预设。
+- `keyshot_apply_camera_preset`：用预设创建或更新命名相机。
 - `keyshot_set_environment`：设置环境。
 - `keyshot_save_scene`：保存场景。
 
+### 自动渲染全部相机
+
+`keyshot_render_all_cameras` 会在同一次 KeyShot 无界面运行中自动读取场景相机并逐个渲染。
+`continueOnError` 默认是 `true`，因此单个相机失败不会阻止其他视角；同名安全文件会自动添加
+`-2`、`-3` 等编号。除非设置 `overwrite: true`，否则不会覆盖已有图片。KeyShot 内部不能激活的
+`last_active` 占位项会被列出并跳过。
+
 ### 材质预设库
 
 `keyshot_apply_material_preset` 会读取一个小的 JSON 注册表，让你用"好记的名字"复用材质，
@@ -539,6 +611,30 @@ examples/codex.example.json
 
 每个预设必须包含 `materialName` 或 `materialPath`。用 `keyshot_list_material_presets` 查看有哪些预设。
 
+### 相机预设库
+
+内置的 `presets/cameras.json` 包含 Front、Back、Left、Right、Top、Bottom 和
+Isometric 七个 KeyShot 标准视角。使用 `keyshot_list_camera_presets` 查看预设，
+使用 `keyshot_apply_camera_preset` 创建或更新命名相机。
+
+把 `KEYSHOT_CAMERA_PRESETS` 指向用户自己的 JSON 文件即可添加自定义预设：
+
+```json
+{
+  "正视图": { "standardView": "front" },
+  "产品主视角": {
+    "position": [4.5, 3.5, 4.5],
+    "lookAt": [0, 0, 0],
+    "up": [0, 1, 0],
+    "description": "自定义绝对坐标相机"
+  }
+}
+```
+
+预设文件既可以使用上面的对象格式，也可以使用每项包含 `name` 的数组格式。
+每个预设只能选择一种形式：填写一个受支持的 `standardView`，或者同时填写
+`position` 与 `lookAt`。MCP 只读取预设文件，不会自动修改它。
+
 ## MCP 提示词和资源
 
 - 提示词：`keyshot_product_render`
@@ -559,9 +655,9 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 
 ## 路线图
 
-- [ ] 自动发现并批量渲染场景中的所有相机
+- [x] 自动发现并批量渲染场景中的所有相机
 - [x] 材质预设库
-- [ ] 相机预设模板
+- [x] 相机预设模板
 - [x] 顺序渲染队列
 - [x] 更安全的输出目录限制
 - [ ] 测试更多 KeyShot 版本
@@ -573,7 +669,7 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 ![KeyShot MCP 自动生成的立方体 Demo](assets/demo/keyshot-mcp-demo.png)
 
 Demo 只使用 `examples/demo` 中项目自己生成的几何体，不包含客户模型或第三方素材。
-设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建相机、保存和真实 PNG 渲染：
+设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建两个相机、自动发现、保存和真实 PNG 渲染：
 
 ```bash
 npm run smoke:keyshot

package/dist/camera-presets.js

@@ -0,0 +1,86 @@
+import fs from "node:fs/promises";
+export const STANDARD_CAMERA_VIEWS = [
+    "front",
+    "back",
+    "left",
+    "right",
+    "top",
+    "bottom",
+    "isometric",
+];
+export async function loadCameraPresets(config) {
+    let raw;
+    try {
+        raw = await fs.readFile(config.cameraPresetsPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Camera presets file is not valid JSON: ${config.cameraPresetsPath}`);
+    }
+    return normalizeCameraPresets(parsed);
+}
+export function normalizeCameraPresets(parsed) {
+    const entries = [];
+    if (Array.isArray(parsed)) {
+        for (const item of parsed) {
+            if (!item || typeof item !== "object")
+                continue;
+            const record = item;
+            if (typeof record.name !== "string" || !record.name)
+                continue;
+            const preset = toCameraPreset(record.name, record);
+            if (preset)
+                entries.push(preset);
+        }
+    }
+    else if (parsed && typeof parsed === "object") {
+        for (const [name, value] of Object.entries(parsed)) {
+            if (!value || typeof value !== "object")
+                continue;
+            const preset = toCameraPreset(name, value);
+            if (preset)
+                entries.push(preset);
+        }
+    }
+    return entries;
+}
+export function findCameraPreset(presets, name) {
+    const lower = name.toLowerCase();
+    return (presets.find((preset) => preset.name === name) ??
+        presets.find((preset) => preset.name.toLowerCase() === lower));
+}
+function toCameraPreset(name, record) {
+    const description = typeof record.description === "string" ? record.description : undefined;
+    const standardView = normalizeStandardView(record.standardView);
+    const position = toVector(record.position);
+    const lookAt = toVector(record.lookAt);
+    const up = toVector(record.up);
+    const hasStandard = standardView !== undefined;
+    const hasAbsolute = position !== undefined || lookAt !== undefined || up !== undefined;
+    if (hasStandard && !hasAbsolute) {
+        return { name, type: "standard", standardView, description };
+    }
+    if (!hasStandard && position && lookAt) {
+        return { name, type: "absolute", position, lookAt, up, description };
+    }
+    return undefined;
+}
+function normalizeStandardView(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.toLowerCase();
+    return STANDARD_CAMERA_VIEWS.find((view) => view === normalized);
+}
+function toVector(value) {
+    if (!Array.isArray(value) || value.length !== 3)
+        return undefined;
+    if (!value.every((item) => typeof item === "number" && Number.isFinite(item)))
+        return undefined;
+    return [value[0], value[1], value[2]];
+}

package/dist/config.js

@@ -15,6 +15,7 @@ export function getConfig() {
         tmpDir: path.join(projectRoot, "work", "tmp"),
         bridgeScriptPath: path.join(projectRoot, "scripts", "keyshot_bridge.py"),
         materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ?? path.join(projectRoot, "presets", "materials.json")),
+        cameraPresetsPath: path.resolve(process.env.KEYSHOT_CAMERA_PRESETS ?? path.join(projectRoot, "presets", "cameras.json")),
     };
 }
 function parseBoolean(value) {

package/dist/index.js

@@ -6,8 +6,9 @@ import { toolResponse, localFailure } from "./result.js";
 import { runKeyShotSerialized } from "./runner.js";
 import { runRenderQueue } from "./queue.js";
 import { loadMaterialPresets, findMaterialPreset } from "./presets.js";
+import { loadCameraPresets, findCameraPreset } from "./camera-presets.js";
 import { VERSION } from "./version.js";
-import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
+import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, applyCameraPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, listCameraPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderAllCamerasSchema, renderAllCamerasInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
 const config = getConfig();
 const server = new McpServer({
     name: "keyshot-mcp",
@@ -72,6 +73,10 @@ server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyS
     const parsed = batchRenderInputSchema.parse(args);
     return toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...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 }));
+});
 server.tool("keyshot_import_model", "Import a model into an optional base scene and save the resulting scene.", importModelSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, {
     operation: "import_model",
     ...args,
@@ -121,6 +126,58 @@ server.tool("keyshot_apply_material_preset", "Apply a named material preset (fro
     }));
 });
 server.tool("keyshot_set_camera", "Create or update a camera from position/look-at vectors and save the resulting scene.", setCameraSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "set_camera", ...args })));
+server.tool("keyshot_list_camera_presets", "List standard and custom camera presets from presets/cameras.json or KEYSHOT_CAMERA_PRESETS.", listCameraPresetsSchema.shape, async () => {
+    try {
+        const presets = await loadCameraPresets(config);
+        return toolResponse({
+            ok: true,
+            data: { presets, count: presets.length, source: config.cameraPresetsPath },
+            outputFiles: [],
+            warnings: presets.length === 0 ? ["No valid camera presets found."] : [],
+            keyshotStdoutTail: "",
+            error: null,
+        });
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+});
+server.tool("keyshot_apply_camera_preset", "Create or update a named camera from a standard or custom camera preset and save the scene.", applyCameraPresetSchema.shape, async (args) => {
+    let presets;
+    try {
+        presets = await loadCameraPresets(config);
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+    const preset = findCameraPreset(presets, args.presetName);
+    if (!preset) {
+        const available = presets.map((entry) => entry.name).join(", ") || "(none)";
+        return toolResponse(localFailure(`Camera preset not found: "${args.presetName}". Available: ${available}`));
+    }
+    const request = preset.type === "standard"
+        ? {
+            operation: "set_standard_camera",
+            scenePath: args.scenePath,
+            standardView: preset.standardView,
+            cameraName: args.cameraName ?? preset.name,
+            outputScenePath: args.outputScenePath,
+        }
+        : {
+            operation: "set_camera",
+            scenePath: args.scenePath,
+            cameraName: args.cameraName ?? preset.name,
+            position: preset.position,
+            lookAt: preset.lookAt,
+            up: preset.up,
+            outputScenePath: args.outputScenePath,
+        };
+    const result = await runKeyShotSerialized(config, request);
+    if (result.data && typeof result.data === "object") {
+        result.data = { presetName: preset.name, presetType: preset.type, ...result.data };
+    }
+    return toolResponse(result);
+});
 server.tool("keyshot_set_environment", "Set a scene environment by name or file when supported by KeyShot headless scripting.", setEnvironmentSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "set_environment", ...args })));
 server.tool("keyshot_save_scene", "Save a KeyShot scene to a new path.", saveSceneSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "save_scene", ...args })));
 const transport = new StdioServerTransport();

package/dist/schemas.js

@@ -36,6 +36,21 @@ export const batchRenderInputSchema = batchRenderSchema.refine((value) => !(valu
     message: "Choose either samples or maxTimeSeconds, not both.",
     path: ["maxTimeSeconds"],
 });
+export const renderAllCamerasSchema = z.object({
+    scenePath: z.string().min(1),
+    outputDir: z.string().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: imageFormat.optional(),
+    overwrite: z.boolean().optional(),
+    continueOnError: z.boolean().default(true),
+});
+export const renderAllCamerasInputSchema = renderAllCamerasSchema.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,
@@ -64,6 +79,13 @@ export const setCameraSchema = z.object({
     distance: z.number().positive().optional(),
     outputScenePath: z.string().min(1),
 });
+export const listCameraPresetsSchema = z.object({});
+export const applyCameraPresetSchema = z.object({
+    scenePath: z.string().min(1),
+    presetName: z.string().min(1),
+    cameraName: z.string().min(1).optional(),
+    outputScenePath: z.string().min(1),
+});
 export const setEnvironmentSchema = z.object({
     scenePath: z.string().min(1),
     environmentName: z.string().min(1).optional(),

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.4.2";
+export const VERSION = "0.6.0";

package/examples/demo/README.md

@@ -4,6 +4,7 @@
 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.
+checks KeyShot, imports the cube, saves and inspects the scene, applies the
+built-in Front and Isometric camera presets, automatically discovers them, and renders both views under
+`outputs/demo/all-cameras`. Generated `.bip` and PNG files remain under
+`outputs/` and are ignored by Git.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local and portable MCP server for KeyShot headless scripting.",
   "type": "module",

package/presets/cameras.json

@@ -0,0 +1,30 @@
+{
+  "Front": {
+    "standardView": "front",
+    "description": "Front standard view / 正视图"
+  },
+  "Back": {
+    "standardView": "back",
+    "description": "Back standard view / 后视图"
+  },
+  "Left": {
+    "standardView": "left",
+    "description": "Left standard view / 左视图"
+  },
+  "Right": {
+    "standardView": "right",
+    "description": "Right standard view / 右视图"
+  },
+  "Top": {
+    "standardView": "top",
+    "description": "Top standard view / 顶视图"
+  },
+  "Bottom": {
+    "standardView": "bottom",
+    "description": "Bottom standard view / 底视图"
+  },
+  "Isometric": {
+    "standardView": "isometric",
+    "description": "Isometric standard view / 等距视图"
+  }
+}

package/scripts/keyshot-smoke.mjs

@@ -1,5 +1,8 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
 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 { runKeyShotSerialized } from "../dist/runner.js";
 
@@ -18,8 +21,23 @@ async function run(label, request) {
   return result;
 }
 
-const status = await run("1/5 KeyShot status", { operation: "status" });
-const imported = await run("2/5 Import and save generated OBJ", {
+async function applyStandardPreset(label, scenePath, presetName, outputScenePath) {
+  const presets = await loadCameraPresets(config);
+  const preset = findCameraPreset(presets, presetName);
+  if (!preset || preset.type !== "standard") {
+    throw new Error(`Standard camera preset not found: ${presetName}`);
+  }
+  return run(label, {
+    operation: "set_standard_camera",
+    scenePath,
+    cameraName: preset.name,
+    standardView: preset.standardView,
+    outputScenePath,
+  });
+}
+
+const status = await run("1/7 KeyShot status", { operation: "status" });
+const imported = await run("2/7 Import and save generated OBJ", {
   operation: "import_model",
   modelPath,
   outputScenePath: "demo/keyshot-mcp-demo-import.bip",
@@ -27,7 +45,7 @@ const imported = await run("2/5 Import and save 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/5 Inspect imported scene", {
+const inspected = await run("3/7 Inspect imported scene", {
   operation: "inspect_scene",
   scenePath: importedScene,
 });
@@ -36,32 +54,64 @@ 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 firstCameraResult = await applyStandardPreset(
+  "4/7 Apply Front camera preset",
+  importedScene,
+  "Front",
+  "demo/keyshot-mcp-demo-preset-front.bip",
+);
+const firstCameraScene = firstCameraResult.outputFiles[0];
+if (!firstCameraScene) throw new Error("Front preset did not return a saved scene path.");
+
+const secondCameraResult = await applyStandardPreset(
+  "5/7 Apply Isometric camera preset",
+  firstCameraScene,
+  "Isometric",
+  "demo/keyshot-mcp-demo-presets.bip",
+);
+const cameraScene = secondCameraResult.outputFiles[0];
+if (!cameraScene) throw new Error("Isometric preset did not return a saved scene path.");
 
-const rendered = await run("5/5 Render real PNG", {
-  operation: "render",
+const rendered = await run("6/7 Discover and render every camera", {
+  operation: "render_all_cameras",
   scenePath: cameraScene,
-  camera: "MCP Demo",
-  outputPath: "demo/keyshot-mcp-demo.png",
+  outputDir: "demo/all-cameras",
   width: 640,
   height: 480,
   maxTimeSeconds: 8,
   format: "png",
+  overwrite: true,
+  continueOnError: true,
 });
 
+const renderData = rendered.data;
+if (!renderData || renderData.failed !== 0 || renderData.succeeded < 2) {
+  throw new Error("All-camera render did not produce at least two successful camera views.");
+}
+
+const namedResults = renderData.results.filter(
+  (entry) => entry.camera === "Front" || entry.camera === "Isometric",
+);
+if (namedResults.length !== 2 || namedResults.some((entry) => !entry.ok)) {
+  throw new Error("The Front and Isometric preset cameras were not both rendered successfully.");
+}
+const hashes = await Promise.all(namedResults.map(async (entry) =>
+  crypto.createHash("sha256").update(await fs.readFile(entry.outputPath)).digest("hex")
+));
+if (hashes[0] === hashes[1]) {
+  throw new Error("The two demo camera renders are identical; expected different viewpoints.");
+}
+const minimumSizes = await Promise.all(namedResults.map(async (entry) => (await fs.stat(entry.outputPath)).size));
+if (minimumSizes.some((size) => size < 10000)) {
+  throw new Error("A demo camera render is unexpectedly small and may be blank.");
+}
+process.stdout.write("7/7 Verify two different camera images... ok\n");
+
 console.log(JSON.stringify({
   keyshotVersion: status.data?.version ?? null,
   objectCount: objects.length,
   scenePath: cameraScene,
-  imagePath: rendered.outputFiles[0] ?? null,
+  cameraCount: renderData.total,
+  renderedImages: rendered.outputFiles,
+  verifiedPresets: namedResults.map((entry) => entry.camera),
 }, null, 2));

package/scripts/keyshot_bridge.py

@@ -37,12 +37,16 @@ def main():
             data = render(payload, output_files, warnings)
         elif operation == "batch_render":
             data = batch_render(payload, output_files, warnings)
+        elif operation == "render_all_cameras":
+            data = render_all_cameras(payload, output_files, warnings)
         elif operation == "import_model":
             data = import_model(payload, output_files, warnings)
         elif operation == "apply_material":
             data = apply_material(payload, output_files, warnings)
         elif operation == "set_camera":
             data = set_camera(payload, output_files, warnings)
+        elif operation == "set_standard_camera":
+            data = set_standard_camera(payload, output_files, warnings)
         elif operation == "set_environment":
             data = set_environment(payload, output_files, warnings)
         elif operation == "save_scene":
@@ -50,7 +54,10 @@ def main():
         else:
             raise RuntimeError("Unsupported operation: %s" % operation)
 
-        write_result(result_path, True, data, output_files, warnings, None)
+        operation_error = None
+        if operation == "render_all_cameras" and data.get("failed", 0) > 0:
+            operation_error = "%s of %s camera render(s) failed." % (data["failed"], data["total"])
+        write_result(result_path, operation_error is None, data, output_files, warnings, operation_error)
     except Exception as exc:
         warnings.append(traceback.format_exc())
         write_result(result_path, False, None, output_files, warnings, str(exc))
@@ -99,6 +106,11 @@ def inspect_scene():
 
 
 def list_cameras():
+    names = camera_names()
+    return {"cameras": names, "count": len(names)}
+
+
+def camera_names():
     raw = safe_list_call("getCameras")
     names = []
     for camera in raw:
@@ -113,8 +125,8 @@ def list_cameras():
             )
         if name is None:
             name = repr(camera)
-        names.append(name)
-    return {"cameras": names, "count": len(names)}
+        names.append(str(name))
+    return names
 
 
 def render(payload, output_files, warnings):
@@ -214,6 +226,100 @@ def batch_render(payload, output_files, warnings):
     }
 
 
+def render_all_cameras(payload, output_files, warnings):
+    scene_path = payload.get("scenePath")
+    output_dir = payload.get("outputDir")
+    discovered_cameras = camera_names()
+    excluded_cameras = [name for name in discovered_cameras if name.lower() == "last_active"]
+    cameras = [name for name in discovered_cameras if name.lower() != "last_active"]
+    width = payload.get("width") or 1920
+    height = payload.get("height") or 1080
+    image_format = payload.get("format") or "png"
+    overwrite = bool(payload.get("overwrite", False))
+    continue_on_error = payload.get("continueOnError", True) is not False
+
+    if not scene_path:
+        raise RuntimeError("scenePath is required")
+    if not output_dir:
+        raise RuntimeError("outputDir is required")
+    if not cameras:
+        raise RuntimeError("No cameras were found in the scene.")
+
+    if excluded_cameras:
+        warnings.append("Skipped KeyShot internal camera placeholder(s): %s" % ", ".join(excluded_cameras))
+
+    os.makedirs(output_dir, exist_ok=True)
+    results = []
+    used_stems = set()
+    stopped = False
+
+    for index, camera in enumerate(cameras):
+        output_path = unique_camera_output_path(output_dir, camera, image_format, used_stems)
+        if stopped:
+            results.append(camera_render_result(index, camera, output_path, False, None, True))
+            continue
+
+        try:
+            if os.path.exists(output_path) and not overwrite:
+                raise RuntimeError("Output already exists and overwrite is false: %s" % output_path)
+
+            render_payload = dict(payload)
+            render_payload["camera"] = camera
+            render_payload["outputPath"] = output_path
+            render_payload["width"] = width
+            render_payload["height"] = height
+            render_payload["format"] = image_format
+            rendered = render(render_payload, output_files, warnings)
+            results.append(camera_render_result(index, camera, rendered.get("rendered"), True, None, False))
+        except Exception as exc:
+            error = str(exc)
+            warnings.append("Camera %s (%s) failed: %s" % (index, camera, error))
+            results.append(camera_render_result(index, camera, output_path, False, error, False))
+            if not continue_on_error:
+                stopped = True
+
+    succeeded = len([item for item in results if item["ok"]])
+    failed = len([item for item in results if not item["ok"] and not item["skipped"]])
+    skipped = len([item for item in results if item["skipped"]])
+    return {
+        "scenePath": scene_path,
+        "outputDir": output_dir,
+        "cameras": cameras,
+        "excludedCameras": excluded_cameras,
+        "total": len(cameras),
+        "succeeded": succeeded,
+        "failed": failed,
+        "skipped": skipped,
+        "continueOnError": continue_on_error,
+        "results": results,
+        "width": width,
+        "height": height,
+        "format": image_format,
+    }
+
+
+def camera_render_result(index, camera, output_path, ok, error, skipped):
+    return {
+        "index": index,
+        "camera": camera,
+        "outputPath": output_path,
+        "ok": ok,
+        "error": error,
+        "skipped": skipped,
+    }
+
+
+def unique_camera_output_path(output_dir, camera, image_format, used_stems):
+    base = safe_filename(camera)
+    stem = base
+    suffix = 2
+    while stem.lower() in used_stems:
+        stem = "%s-%s" % (base, suffix)
+        suffix += 1
+    used_stems.add(stem.lower())
+    return os.path.join(output_dir, "%s.%s" % (stem, image_format))
+
+
 def import_model(payload, output_files, warnings):
     model_path = payload.get("modelPath")
     output_scene_path = payload.get("outputScenePath")
@@ -298,6 +404,7 @@ def set_camera(payload, output_files, warnings):
 
     if position is None or look_at is None:
         raise RuntimeError("position and lookAt are required")
+    direction = tuple(look_at[index] - position[index] for index in range(3))
 
     camera = first_camera_object(
         lambda: lux.getCamera(camera_name),
@@ -305,47 +412,53 @@ def set_camera(payload, output_files, warnings):
         lambda: lux.createCamera(camera_name),
     )
 
-    if camera is None and hasattr(lux, "saveCamera"):
-        try:
-            # Current KeyShot versions expose cameras as names rather than camera
-            # objects. saveCamera creates the named camera and setCamera activates it.
-            call_variants(
-                "create named camera",
-                lambda: lux.saveCamera(camera_name),
-                lambda: lux.saveCamera(),
-            )
-            if hasattr(lux, "setCamera"):
-                call_variants("activate camera", lambda: lux.setCamera(camera_name))
-        except RuntimeError:
-            pass
-
     if camera is not None:
         # Object-level API is available: drive the camera object directly.
-        call_variants("set camera position", lambda: camera.setPosition(tuple(position)))
         call_variants("set camera look-at", lambda: camera.setLookAt(tuple(look_at)))
+        call_variants("set camera position", lambda: camera.setPosition(tuple(position)))
+        if hasattr(camera, "setDirection"):
+            call_variants("set camera direction", lambda: camera.setDirection(direction))
         call_variants("set camera up", lambda: camera.setUp(tuple(up)))
     else:
         # No camera object could be obtained: fall back to the lux-level setters,
-        # which address the camera by name. This path never dereferences a None
-        # camera object, so it cannot crash when camera creation is unsupported.
-        call_variants(
-            "set camera position",
-            lambda: lux.setCameraPosition(pos=tuple(position)),
-            lambda: lux.setCameraPosition(tuple(position)),
-            lambda: lux.setCameraPosition(camera_name, tuple(position)),
-        )
+        # which operate on the active camera. Existing named cameras are activated
+        # first. Missing cameras are saved under their new name after the transform
+        # is set; saveCamera is a snapshot operation, not a camera constructor.
+        if camera_name in camera_names() and hasattr(lux, "setCamera"):
+            call_variants("activate camera", lambda: lux.setCamera(camera_name))
         call_variants(
             "set camera look-at",
             lambda: lux.setCameraLookAt(pt=tuple(look_at)),
             lambda: lux.setCameraLookAt(0, tuple(look_at)),
             lambda: lux.setCameraLookAt(camera_name, tuple(look_at)),
         )
+        call_variants(
+            "set camera position",
+            lambda: lux.setCameraPosition(pos=tuple(position)),
+            lambda: lux.setCameraPosition(tuple(position)),
+            lambda: lux.setCameraPosition(camera_name, tuple(position)),
+        )
+        if hasattr(lux, "setCameraDirection"):
+            call_variants(
+                "set camera direction",
+                lambda: lux.setCameraDirection(dir=direction),
+                lambda: lux.setCameraDirection(direction),
+            )
         call_variants(
             "set camera up",
             lambda: lux.setCameraUp(up=tuple(up)),
             lambda: lux.setCameraUp(tuple(up)),
             lambda: lux.setCameraUp(camera_name, tuple(up)),
         )
+        if hasattr(lux, "saveCamera"):
+            try:
+                call_variants(
+                    "save named camera",
+                    lambda: lux.saveCamera(),
+                    lambda: lux.saveCamera(camera_name),
+                )
+            except RuntimeError:
+                warnings.append("The active camera was updated, but this KeyShot version could not save the named view.")
 
     save_to(output_scene_path)
     output_files.append(output_scene_path)
@@ -358,6 +471,54 @@ def set_camera(payload, output_files, warnings):
     }
 
 
+def set_standard_camera(payload, output_files, warnings):
+    output_scene_path = payload.get("outputScenePath")
+    camera_name = payload.get("cameraName") or "MCP Camera"
+    standard_view = str(payload.get("standardView") or "").lower()
+    view_constants = {
+        "front": "VIEW_FRONT",
+        "back": "VIEW_BACK",
+        "left": "VIEW_LEFT",
+        "right": "VIEW_RIGHT",
+        "top": "VIEW_TOP",
+        "bottom": "VIEW_BOTTOM",
+        "isometric": "VIEW_ISOMETRIC",
+    }
+
+    constant_name = view_constants.get(standard_view)
+    if constant_name is None:
+        raise RuntimeError("Unsupported standard camera view: %s" % standard_view)
+    if not hasattr(lux, "setStandardView"):
+        raise RuntimeError("KeyShot lux.setStandardView is not available.")
+    if not hasattr(lux, constant_name):
+        raise RuntimeError("KeyShot camera constant is not available: %s" % constant_name)
+
+    if camera_name in camera_names():
+        if not hasattr(lux, "setCamera"):
+            raise RuntimeError("KeyShot cannot activate the existing camera: %s" % camera_name)
+        call_non_false_variants("activate camera", lambda: lux.setCamera(camera_name))
+    else:
+        call_non_false_variants(
+            "create camera",
+            lambda: lux.newCamera(camera_name),
+            lambda: lux.createCamera(camera_name),
+        )
+
+    call_variants("set standard camera view", lambda: lux.setStandardView(getattr(lux, constant_name)))
+    call_variants(
+        "save standard camera",
+        lambda: lux.saveCamera(),
+        lambda: lux.saveCamera(camera_name),
+    )
+    save_to(output_scene_path)
+    output_files.append(output_scene_path)
+    return {
+        "cameraName": camera_name,
+        "standardView": standard_view,
+        "savedScene": output_scene_path,
+    }
+
+
 def set_environment(payload, output_files, warnings):
     output_scene_path = payload.get("outputScenePath")
     environment_name = payload.get("environmentName")
@@ -491,6 +652,19 @@ def call_variants(label, *callbacks):
     raise RuntimeError("%s is unsupported or failed: %s" % (label, " | ".join(errors)))
 
 
+def call_non_false_variants(label, *callbacks):
+    errors = []
+    for callback in callbacks:
+        try:
+            value = callback()
+            if value is not False:
+                return value
+            errors.append("returned false")
+        except Exception as exc:
+            errors.append(str(exc))
+    raise RuntimeError("%s is unsupported or failed: %s" % (label, " | ".join(errors)))
+
+
 def first_success(*callbacks, default=None):
     for callback in callbacks:
         try:

package/server.json

@@ -9,12 +9,12 @@
     "url": "https://github.com/truman-t3/keyshot-mcp",
     "source": "github"
   },
-  "version": "0.4.2",
+  "version": "0.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "keyshot-mcp",
-      "version": "0.4.2",
+      "version": "0.6.0",
       "transport": {
         "type": "stdio"
       },
@@ -24,6 +24,12 @@
           "description": "Absolute path to KeyShot headless, or a command available on PATH.",
           "isRequired": true,
           "isSecret": false
+        },
+        {
+          "name": "KEYSHOT_CAMERA_PRESETS",
+          "description": "Optional path to a user-managed camera preset JSON file.",
+          "isRequired": false,
+          "isSecret": false
         }
       ]
     }