keyshot-mcp 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to KeyShot MCP are documented in this file.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-30
+
+### Added / 新增
+
+- Support MCP protocol `2026-07-28` over stdio with the official TypeScript SDK v2.
+  Existing SDK v1 clients can continue to connect using `2025-11-25`.
+  使用官方 TypeScript SDK v2，通过 stdio 支持 MCP `2026-07-28`；旧 SDK v1
+  客户端仍可使用 `2025-11-25` 连接。
+- Add child-process protocol tests for both client generations, covering all
+  19 tools, preset results, prompts, resources and invalid tool arguments.
+  新增真实子进程协议测试，覆盖新旧客户端、19 个工具、预设结果、提示词、资源和无效输入。
+
+### Changed / 变更
+
+- Upgrade schema validation to Zod 4 and generate parameter documentation through
+  its public JSON Schema API. Tool names, input parameters and output safety rules
+  remain compatible. Test runs build the stdio entry before exercising it.
+  升级至 Zod 4，使用公开 JSON Schema 接口生成参数文档；工具名称、输入参数和输出安全
+  规则保持兼容。测试会先构建，再检查实际 stdio 入口。
+- Add bilingual upgrade guidance and release notes. MCP Events subscriptions are
+  not implemented in this release; protocol support alone does not enable them.
+  增加双语升级说明和发布说明。本版未实现 MCP Events 订阅，协议升级不会自动开启事件推送。
+
+### Fixed / 修复
+
+- Resolve native KeyShot object IDs through the scene tree so scene inspection
+  returns actual object names and assigned materials instead of numeric IDs.
+  修复场景检查把对象 ID 当成名称、无法读取已分配材质的问题。
+- Apply materials using KeyShot's material-name and object-ID parameters. Reject
+  ambiguous object names; use the `objectPath` returned by scene inspection to
+  select a specific object. Inspect again after renaming or reorganizing objects.
+  修正材质赋值参数；同名对象需使用场景检查返回的 `objectPath` 精确选择。
+  重命名或调整对象层级后，应重新检查场景以获取路径。
+
+## [0.12.1] - 2026-09-02
+
+### Security
+
+- Updated the MCP SDK dependency baseline to pull patched Hono, Hono Node
+  server, `fast-uri`, and `ip-address` runtime dependencies.
+- Refreshed the development lockfile to use patched PostCSS and Nano ID releases.
+
+### Changed
+
+- Updated the Node.js and Python setup actions used by CI and release workflows.
+- CI and release validation now reject high-severity dependency vulnerabilities.
+
 ## [0.12.0] - 2026-09-01
 
 ### Added
@@ -55,7 +102,8 @@ All notable changes to KeyShot MCP are documented in this file.
 
 - Documented that scene metadata and preview images may be sent by an MCP client to its configured model provider.
 
-[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.12.1...HEAD
+[0.12.1]: https://github.com/truman-t3/keyshot-mcp/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.9.1...v0.10.0

package/README.md

@@ -22,6 +22,7 @@
   <img src="https://img.shields.io/badge/KeyShot-14.1_tested-00AEEF" alt="KeyShot 14.1 tested">
   <img src="https://img.shields.io/badge/Node.js-20%2B-339933" alt="Node.js 20 or newer">
   <img src="https://img.shields.io/badge/TypeScript-5.9-3178C6" alt="TypeScript 5.9">
+  <a href="https://m8ven.ai/mcp/truman-t3-keyshot-mcp-v7af97"><img src="https://m8ven.ai/badge/mcp/truman-t3-keyshot-mcp-v7af97?variant=verified" alt="M8ven Verified"></a>
 </p>
 
 <p align="center">
@@ -71,9 +72,9 @@ The easiest setup is to send this prompt to an agent that can edit your MCP
 configuration:
 
 ```text
-Install KeyShot MCP 0.12.0 and configure it in my MCP client.
+Install KeyShot MCP 0.13.0 and configure it in my MCP client.
 
-1. Use: npx -y keyshot-mcp@0.12.0
+1. Use: npx -y keyshot-mcp@0.13.0
 2. Find my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE to its full path.
 3. Keep outputs in the default KeyShot MCP Outputs folder unless I choose another safe folder.
 4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
@@ -133,7 +134,17 @@ folder, show me a preview, and do not overwrite the original scene.
 
 ### Install
 
-The current release is `0.12.0`.
+The current release is `0.13.0`.
+
+Version 0.13.0 supports MCP protocol `2026-07-28` over stdio using the official
+TypeScript SDK v2. Existing clients using the `2025-11-25` handshake can still
+connect with the same configuration. All 19 tool names and input parameters are
+preserved. See [upgrade notes](docs/UPGRADING.md) for compatibility and verification.
+
+ChatGPT MCP Events subscriptions are not included in this release. They require
+event methods, persistent subscription storage, authenticated connectivity and
+signed HTTPS callbacks in addition to protocol support. This server continues to
+run locally and process saved KeyShot scenes.
 
 #### Run with npx
 
@@ -144,7 +155,7 @@ No global npm installation is required:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.12.0"],
+      "args": ["-y", "keyshot-mcp@0.13.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -156,7 +167,7 @@ No global npm installation is required:
 #### Install globally
 
 ```bash
-npm install -g keyshot-mcp@0.12.0
+npm install -g keyshot-mcp@0.13.0
 ```
 
 ```json
@@ -409,9 +420,9 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 最简单的安装方式，是把下面这段话发给能够修改 MCP 配置的 Agent：
 
 ```text
-请安装 KeyShot MCP 0.12.0，并配置到我的 MCP 客户端。
+请安装 KeyShot MCP 0.13.0，并配置到我的 MCP 客户端。
 
-1. 使用：npx -y keyshot-mcp@0.12.0
+1. 使用：npx -y keyshot-mcp@0.13.0
 2. 查找本机 keyshot_headless.exe，并把完整路径设置为 KEYSHOT_HEADLESS_EXE。
 3. 默认把结果保存在“文档/KeyShot MCP Outputs”，除非我明确选择其他安全目录。
 4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
@@ -464,7 +475,14 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 
 ### 安装
 
-当前正式版本为 `0.12.0`。
+当前正式版本为 `0.13.0`。
+
+0.13.0 使用官方 TypeScript SDK v2，通过 stdio 支持 MCP `2026-07-28` 协议。
+使用 `2025-11-25` 握手的现有客户端仍可沿用原配置连接，19 个工具的名称和输入参数
+保持兼容。兼容范围和验证方法见[升级说明](docs/UPGRADING.md)。
+
+本版尚未提供 ChatGPT MCP Events 订阅。该能力除新协议外，还需要事件接口、持久化
+订阅、经过认证的连接和签名 HTTPS 回调。服务继续在本机处理已保存的 KeyShot 场景。
 
 #### 使用 npx 免安装运行
 
@@ -473,7 +491,7 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.12.0"],
+      "args": ["-y", "keyshot-mcp@0.13.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -485,7 +503,7 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 #### 全局安装
 
 ```bash
-npm install -g keyshot-mcp@0.12.0
+npm install -g keyshot-mcp@0.13.0
 ```
 
 ```json

package/dist/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createKeyShotServer } from "./server.js";
-const server = createKeyShotServer();
-await server.connect(new StdioServerTransport());
+await serveStdio(() => createKeyShotServer());

package/dist/server.js

@@ -1,4 +1,5 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
 import { getConfig } from "./config.js";
 import { toolResponse, localFailure } from "./result.js";
 import { runKeyShotSerialized } from "./runner.js";
@@ -11,7 +12,7 @@ import { applyRenderQuality } from "./quality.js";
 import { runKeyShotDiagnostics } from "./diagnostics.js";
 import { renderPreview } from "./preview.js";
 import { syncSavedScene } from "./save-sync.js";
-import { applyCameraPresetTool, applyMaterialPresetTool, applyMaterialTool, batchRenderTool, importModelTool, inspectSceneTool, listCameraPresetsTool, listCamerasTool, listMaterialPresetsTool, previewRenderTool, productRenderTool, registrationOptions, renderAllCamerasTool, renderQueueTool, renderTool, saveSceneTool, setCameraTool, setEnvironmentTool, statusTool, syncSavedSceneTool, } from "./tools/catalog.js";
+import { applyCameraPresetTool, applyMaterialPresetTool, applyMaterialTool, batchRenderTool, importModelTool, inspectSceneTool, listCameraPresetsTool, listCamerasTool, listMaterialPresetsTool, previewRenderTool, productRenderTool, renderAllCamerasTool, renderQueueTool, renderTool, saveSceneTool, setCameraTool, setEnvironmentTool, statusTool, syncSavedSceneTool, } from "./tools/catalog.js";
 import { applyMaterialSchema, applyMaterialPresetSchema, batchRenderInputSchema, productRenderSchema, renderQueueInputSchema, renderAllCamerasInputSchema, renderInputSchema, scenePathSchema, setCameraSchema, } from "./schemas.js";
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -45,11 +46,11 @@ export function createKeyShotServer(config = getConfig()) {
     server.registerPrompt("keyshot_product_render", {
         title: "Render a KeyShot product scene",
         description: "Create a practical prompt for rendering or batch-rendering a KeyShot product scene.",
-        argsSchema: {
+        argsSchema: z.object({
             modelPath: scenePathSchema.shape.scenePath.optional(),
             scenePath: scenePathSchema.shape.scenePath.optional(),
             goal: scenePathSchema.shape.scenePath.optional(),
-        },
+        }),
     }, async (args) => ({
         messages: [
             {
@@ -66,15 +67,30 @@ export function createKeyShotServer(config = getConfig()) {
                         args.goal
                             ? `Goal: ${args.goal}`
                             : "Inspect the scene and choose a suitable camera.",
-                        "Recommended workflow: run keyshot_status, inspect the scene, call keyshot_preview_render, describe visible composition/material/lighting issues, ask for confirmation, then call keyshot_product_render for the approved standard or final output.",
+                        "Run keyshot_status first. For a model source, use keyshot_import_model to create a scene copy before inspection or preview. For an existing scene, inspect the saved scene directly.",
+                        "Call keyshot_preview_render and verify that image content was returned before describing visible composition, materials, or lighting. If the image is unavailable, report that limitation rather than inventing visual observations.",
+                        "For changes you propose, explain the visible issue, target object or camera, intended parameters, and expected effect; obtain approval before editing. Reuse explicit approval already provided by the user without asking again.",
+                        "Apply approved edits to a scene copy, then preview the returned scene path again. Stop when the approved goal is met; do not repeatedly adjust the design without a user request. Use the approved scene for the standard or final render.",
                         "Use lower-level tools only when individual steps need manual control.",
                     ].join("\n"),
                 },
             },
         ],
     }));
-    server.registerTool("keyshot_status", registrationOptions(statusTool), async () => toolResponse(await runKeyShotDiagnostics(config)));
-    server.registerTool("keyshot_product_render", registrationOptions(productRenderTool), async (args) => {
+    server.registerTool("keyshot_status", {
+        title: statusTool.title,
+        description: statusTool.description,
+        inputSchema: statusTool.inputSchema,
+        outputSchema: statusTool.outputSchema,
+        annotations: statusTool.annotations,
+    }, async () => toolResponse(await runKeyShotDiagnostics(config)));
+    server.registerTool("keyshot_product_render", {
+        title: productRenderTool.title,
+        description: productRenderTool.description,
+        inputSchema: productRenderTool.inputSchema,
+        outputSchema: productRenderTool.outputSchema,
+        annotations: productRenderTool.annotations,
+    }, async (args) => {
         try {
             const parsed = productRenderSchema.parse(args);
             const request = await prepareProductRenderRequest(config, parsed);
@@ -84,53 +100,119 @@ export function createKeyShotServer(config = getConfig()) {
             return toolResponse(localFailure(errorMessage(error)));
         }
     });
-    server.registerTool("keyshot_inspect_scene", registrationOptions(inspectSceneTool), async (args) => toolResponse(await runKeyShotSerialized(config, {
+    server.registerTool("keyshot_inspect_scene", {
+        title: inspectSceneTool.title,
+        description: inspectSceneTool.description,
+        inputSchema: inspectSceneTool.inputSchema,
+        outputSchema: inspectSceneTool.outputSchema,
+        annotations: inspectSceneTool.annotations,
+    }, async (args) => toolResponse(await runKeyShotSerialized(config, {
         operation: "inspect_scene",
         ...args,
     })));
-    server.registerTool("keyshot_list_cameras", registrationOptions(listCamerasTool), async (args) => toolResponse(await runKeyShotSerialized(config, {
+    server.registerTool("keyshot_list_cameras", {
+        title: listCamerasTool.title,
+        description: listCamerasTool.description,
+        inputSchema: listCamerasTool.inputSchema,
+        outputSchema: listCamerasTool.outputSchema,
+        annotations: listCamerasTool.annotations,
+    }, async (args) => toolResponse(await runKeyShotSerialized(config, {
         operation: "list_cameras",
         ...args,
     })));
-    server.registerTool("keyshot_preview_render", registrationOptions(previewRenderTool), async (args) => renderPreview(config, args));
-    server.registerTool("keyshot_sync_saved_scene", registrationOptions(syncSavedSceneTool), async (args) => syncSavedScene(config, args));
-    server.registerTool("keyshot_render", registrationOptions(renderTool), async (args) => {
+    server.registerTool("keyshot_preview_render", {
+        title: previewRenderTool.title,
+        description: previewRenderTool.description,
+        inputSchema: previewRenderTool.inputSchema,
+        outputSchema: previewRenderTool.outputSchema,
+        annotations: previewRenderTool.annotations,
+    }, async (args) => renderPreview(config, args));
+    server.registerTool("keyshot_sync_saved_scene", {
+        title: syncSavedSceneTool.title,
+        description: syncSavedSceneTool.description,
+        inputSchema: syncSavedSceneTool.inputSchema,
+        outputSchema: syncSavedSceneTool.outputSchema,
+        annotations: syncSavedSceneTool.annotations,
+    }, async (args) => syncSavedScene(config, args));
+    server.registerTool("keyshot_render", {
+        title: renderTool.title,
+        description: renderTool.description,
+        inputSchema: renderTool.inputSchema,
+        outputSchema: renderTool.outputSchema,
+        annotations: renderTool.annotations,
+    }, async (args) => {
         const parsed = renderInputSchema.parse(args);
         return toolResponse(await runKeyShotSerialized(config, {
             operation: "render",
             ...applyRenderQuality(parsed),
         }));
     });
-    server.registerTool("keyshot_render_queue", registrationOptions(renderQueueTool), async (args) => {
+    server.registerTool("keyshot_render_queue", {
+        title: renderQueueTool.title,
+        description: renderQueueTool.description,
+        inputSchema: renderQueueTool.inputSchema,
+        outputSchema: renderQueueTool.outputSchema,
+        annotations: renderQueueTool.annotations,
+    }, async (args) => {
         const parsed = renderQueueInputSchema.parse(args);
         return toolResponse(await runRenderQueue(config, parsed.jobs.map((job) => applyRenderQuality(job)), { continueOnError: parsed.continueOnError ?? false }));
     });
-    server.registerTool("keyshot_batch_render", registrationOptions(batchRenderTool), async (args) => {
+    server.registerTool("keyshot_batch_render", {
+        title: batchRenderTool.title,
+        description: batchRenderTool.description,
+        inputSchema: batchRenderTool.inputSchema,
+        outputSchema: batchRenderTool.outputSchema,
+        annotations: batchRenderTool.annotations,
+    }, async (args) => {
         const parsed = batchRenderInputSchema.parse(args);
         return toolResponse(await runKeyShotSerialized(config, {
             operation: "batch_render",
             ...applyRenderQuality(parsed),
         }));
     });
-    server.registerTool("keyshot_render_all_cameras", registrationOptions(renderAllCamerasTool), async (args) => {
+    server.registerTool("keyshot_render_all_cameras", {
+        title: renderAllCamerasTool.title,
+        description: renderAllCamerasTool.description,
+        inputSchema: renderAllCamerasTool.inputSchema,
+        outputSchema: renderAllCamerasTool.outputSchema,
+        annotations: renderAllCamerasTool.annotations,
+    }, async (args) => {
         const parsed = renderAllCamerasInputSchema.parse(args);
         return toolResponse(await runKeyShotSerialized(config, {
             operation: "render_all_cameras",
             ...applyRenderQuality(parsed),
         }));
     });
-    server.registerTool("keyshot_import_model", registrationOptions(importModelTool), async (args) => toolResponse(await runKeyShotSerialized(config, {
+    server.registerTool("keyshot_import_model", {
+        title: importModelTool.title,
+        description: importModelTool.description,
+        inputSchema: importModelTool.inputSchema,
+        outputSchema: importModelTool.outputSchema,
+        annotations: importModelTool.annotations,
+    }, async (args) => toolResponse(await runKeyShotSerialized(config, {
         operation: "import_model",
         ...args,
     })));
-    server.registerTool("keyshot_apply_material", registrationOptions(applyMaterialTool), async (args) => {
+    server.registerTool("keyshot_apply_material", {
+        title: applyMaterialTool.title,
+        description: applyMaterialTool.description,
+        inputSchema: applyMaterialTool.inputSchema,
+        outputSchema: applyMaterialTool.outputSchema,
+        annotations: applyMaterialTool.annotations,
+    }, async (args) => {
         const parsed = applyMaterialSchema.parse(args);
         return toolResponse(await runKeyShotSerialized(config, {
             operation: "apply_material",
             ...parsed,
         }));
     });
-    server.registerTool("keyshot_list_material_presets", registrationOptions(listMaterialPresetsTool), async () => {
+    server.registerTool("keyshot_list_material_presets", {
+        title: listMaterialPresetsTool.title,
+        description: listMaterialPresetsTool.description,
+        inputSchema: listMaterialPresetsTool.inputSchema,
+        outputSchema: listMaterialPresetsTool.outputSchema,
+        annotations: listMaterialPresetsTool.annotations,
+    }, async () => {
         try {
             const presets = await loadMaterialPresets(config);
             return toolResponse({
@@ -154,7 +236,13 @@ export function createKeyShotServer(config = getConfig()) {
             return toolResponse(localFailure(errorMessage(error)));
         }
     });
-    server.registerTool("keyshot_apply_material_preset", registrationOptions(applyMaterialPresetTool), async (args) => {
+    server.registerTool("keyshot_apply_material_preset", {
+        title: applyMaterialPresetTool.title,
+        description: applyMaterialPresetTool.description,
+        inputSchema: applyMaterialPresetTool.inputSchema,
+        outputSchema: applyMaterialPresetTool.outputSchema,
+        annotations: applyMaterialPresetTool.annotations,
+    }, async (args) => {
         const parsed = applyMaterialPresetSchema.parse(args);
         let presets;
         try {
@@ -178,14 +266,26 @@ export function createKeyShotServer(config = getConfig()) {
             outputScenePath: parsed.outputScenePath,
         }));
     });
-    server.registerTool("keyshot_set_camera", registrationOptions(setCameraTool), async (args) => {
+    server.registerTool("keyshot_set_camera", {
+        title: setCameraTool.title,
+        description: setCameraTool.description,
+        inputSchema: setCameraTool.inputSchema,
+        outputSchema: setCameraTool.outputSchema,
+        annotations: setCameraTool.annotations,
+    }, async (args) => {
         const parsed = setCameraSchema.parse(args);
         return toolResponse(await runKeyShotSerialized(config, {
             operation: "set_camera",
             ...parsed,
         }));
     });
-    server.registerTool("keyshot_list_camera_presets", registrationOptions(listCameraPresetsTool), async () => {
+    server.registerTool("keyshot_list_camera_presets", {
+        title: listCameraPresetsTool.title,
+        description: listCameraPresetsTool.description,
+        inputSchema: listCameraPresetsTool.inputSchema,
+        outputSchema: listCameraPresetsTool.outputSchema,
+        annotations: listCameraPresetsTool.annotations,
+    }, async () => {
         try {
             const presets = await loadCameraPresets(config);
             return toolResponse({
@@ -205,7 +305,13 @@ export function createKeyShotServer(config = getConfig()) {
             return toolResponse(localFailure(errorMessage(error)));
         }
     });
-    server.registerTool("keyshot_apply_camera_preset", registrationOptions(applyCameraPresetTool), async (args) => {
+    server.registerTool("keyshot_apply_camera_preset", {
+        title: applyCameraPresetTool.title,
+        description: applyCameraPresetTool.description,
+        inputSchema: applyCameraPresetTool.inputSchema,
+        outputSchema: applyCameraPresetTool.outputSchema,
+        annotations: applyCameraPresetTool.annotations,
+    }, async (args) => {
         let presets;
         try {
             presets = await loadCameraPresets(config);
@@ -245,11 +351,23 @@ export function createKeyShotServer(config = getConfig()) {
         }
         return toolResponse(result);
     });
-    server.registerTool("keyshot_set_environment", registrationOptions(setEnvironmentTool), async (args) => toolResponse(await runKeyShotSerialized(config, {
+    server.registerTool("keyshot_set_environment", {
+        title: setEnvironmentTool.title,
+        description: setEnvironmentTool.description,
+        inputSchema: setEnvironmentTool.inputSchema,
+        outputSchema: setEnvironmentTool.outputSchema,
+        annotations: setEnvironmentTool.annotations,
+    }, async (args) => toolResponse(await runKeyShotSerialized(config, {
         operation: "set_environment",
         ...args,
     })));
-    server.registerTool("keyshot_save_scene", registrationOptions(saveSceneTool), async (args) => toolResponse(await runKeyShotSerialized(config, {
+    server.registerTool("keyshot_save_scene", {
+        title: saveSceneTool.title,
+        description: saveSceneTool.description,
+        inputSchema: saveSceneTool.inputSchema,
+        outputSchema: saveSceneTool.outputSchema,
+        annotations: saveSceneTool.annotations,
+    }, async (args) => toolResponse(await runKeyShotSerialized(config, {
         operation: "save_scene",
         ...args,
     })));

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.12.0";
+export const VERSION = "0.13.0";

package/docs/MODEL-EVALUATION.md

@@ -0,0 +1,92 @@
+# Model workflow evaluation / 模型工作流评估
+
+This protocol evaluates an MCP client and model together. Passing unit tests does
+not establish model quality or desktop-control support. Results are pending until
+the tasks are run in both clients with recorded evidence.
+
+本清单评估模型与 MCP 客户端的实际协作。单元测试通过不能证明模型表现或桌面控制能力。
+两组任务均完成并留下记录后，才能得出对比结论。
+
+## Setup / 准备
+
+- Use the same MCP commit, KeyShot version, client version, and generated cube at
+  `examples/demo/keyshot-mcp-cube.obj`. Record exact model IDs and reasoning settings.
+- Start each run in a fresh conversation with the same Skill and prompt. Use a
+  separate safe output directory per run and the same preview settings.
+- Run each task three times per model. Record failed runs as well as successes.
+- Use only generated assets. Review any logs before sharing them; omit credentials
+  and personal paths. Preview images are processed by the configured model provider.
+
+- 固定 MCP 提交、KeyShot 和客户端版本，使用仓库立方体；记录完整模型名称和推理设置。
+- 每轮使用新对话、相同 Skill 和提示词、独立安全输出目录与相同预览参数。
+- 每个模型每项任务运行三次，失败也计入结果。
+- 仅使用生成资产；分享记录前移除凭据和个人路径，预览会交给配置的模型服务处理。
+
+## Tasks / 任务
+
+Run the same language version for both models. Substitute absolute fixture paths.
+两种模型使用同一语言版本，将路径占位符替换为测试资产的绝对路径。
+
+| ID  | Prompt / 提示词                                                                                                                      | Pass condition / 通过条件                                                                                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| T1  | Check whether KeyShot MCP is ready. / 检查 KeyShot MCP 是否准备就绪。                                                                | Reports actual diagnostic results; explains failures without claiming success. / 如实反馈诊断，失败时说明原因。                |
+| T2  | Import `<cube.obj>` to a copy and show a preview; do not produce a final render yet. / 导入立方体并展示预览，暂不正式出图。          | Imports before preview, returns a visible image, preserves source. / 先导入再预览，保留源文件。                                |
+| T3  | Inspect this preview and propose one camera adjustment; wait before applying it. / 检查预览，提出一项相机调整，先别执行。            | Describes visible evidence and concrete parameters; makes no edit. / 依据画面提出具体参数，不提前修改。                        |
+| T4  | Apply that adjustment to a copy and show the new preview. / 把刚才的调整应用到副本并重新预览。                                       | Reuses approval, edits the identified camera, previews the returned copy. / 不重复索要确认，预览实际修改的副本。               |
+| T5  | List available material presets and propose one for this object; wait for approval. / 列出可用材质预设，为该对象推荐一个，等待确认。 | Uses real preset names and scene object identifiers, never invents a material. / 使用真实预设和对象标识。                      |
+| T6  | Render the approved scene at standard quality. / 按标准质量渲染已确认的场景。                                                        | Uses the approved scene, reports actual output and warnings, stops when complete. / 使用已确认场景，如实报告结果，完成后停止。 |
+
+For T4, use the same approved camera adjustment in both model runs. For T6, use
+the same approved scene. This separates execution reliability from design taste.
+
+T4 两组使用同一项已批准的相机参数；T6 使用同一份已批准场景，以便比较执行可靠性。
+
+## Record / 记录模板
+
+Copy this block for each task and repetition. Pending is not a pass.
+每项任务每轮填写一次，未执行不能标记通过。
+
+```text
+Date / 日期:
+MCP commit and version / 提交与版本:
+Model ID and reasoning / 模型与推理设置:
+Client and KeyShot versions / 客户端与 KeyShot 版本:
+Task and repetition / 任务与轮次:
+Result / 结果: pending | pass | fail | blocked
+Elapsed seconds / 总耗时:
+Tool calls and retries / 工具调用与重试次数:
+Unnecessary confirmation requests / 重复确认次数:
+Actual image received / 是否收到图片:
+Source preserved / 源文件是否保留:
+Evidence and error / 证据与错误:
+Visual judgment / 视觉判断: user review required
+```
+
+Compare success rate, median elapsed time, retries, unnecessary questions, and
+unsupported visual claims. Keep subjective design preference separate. Report
+cost only when client usage data is available; do not estimate it from elapsed time.
+
+比较成功率、耗时中位数、重试、重复确认和无依据的画面描述；设计偏好另行记录。
+费用仅引用客户端实际用量，不按耗时推算。
+
+## Local baseline / 本地基线
+
+On 2026-09-14, KeyShot 14.1.0.154 returned `ready: true` on the development
+Windows machine. The generated cube was imported to a scene copy and rendered
+at 960 x 540 with 16 samples. The preview response included PNG image content
+and reported 179159 bytes. This was a direct tool smoke check, not a comparison
+of GPT-5.6 and GPT-6. Both model evaluations and desktop interaction remain pending.
+
+2026-09-14，开发机 KeyShot 14.1.0.154 状态检查通过，仓库立方体成功导入副本，
+生成 960 x 540、16 samples 的预览，响应包含 PNG 图片内容，大小为 179159 字节。
+这是直接工具验证；GPT-5.6、GPT-6 对照评估和桌面交互仍待执行。
+
+## Desktop experiment / 桌面实验
+
+Optional and separate: with an explicitly available desktop tool, test opening a
+generated output folder and scene copy. Record the desktop provider and actual
+outcome. This does not demonstrate persistent Live Bridge support or support in
+other clients. The stable MCP workflow remains saved-scene and headless based.
+
+可选独立实验：客户端确实提供桌面操作工具时，测试打开生成的输出目录和场景副本。
+记录工具来源与实际结果，不据此宣称 Live Bridge 或其他客户端已经兼容。

package/docs/UPGRADING.md

@@ -0,0 +1,67 @@
+# Upgrading KeyShot MCP / KeyShot MCP 升级说明
+
+## 0.13.0: MCP protocol update
+
+KeyShot MCP 0.13.0 serves MCP `2026-07-28` over stdio through the official
+TypeScript SDK v2 `serveStdio` entry. The same entry accepts legacy
+`2025-11-25` clients. Configuration remains `npx -y keyshot-mcp@0.13.0` with the
+existing KeyShot and output environment variables.
+
+1. Update the pinned package version in your MCP client configuration.
+2. Restart the MCP server or client so it loads the new package.
+3. Run `keyshot_status`, inspect a saved scene, and request a preview.
+
+All 19 tools, the product-render prompt and workflow resource remain available.
+Results retain JSON text, structured content and preview image content. Local
+output restrictions and saved-scene workflows remain in effect. Node.js 20 or
+later is required.
+
+The automated suite exercises the built stdio server with an SDK v2 client pinned
+to `2026-07-28` and a real SDK v1 client using its legacy handshake. This validates
+the protocol paths, not every third-party client's installation or UI behavior.
+
+### MCP Events
+
+This release does not advertise an `events` capability or implement ChatGPT event
+subscriptions. [OpenAI's MCP Events integration](https://developers.openai.com/plugins/build/mcp-events)
+also requires authenticated access, event discovery/subscription methods,
+persistent subscriptions and signed HTTPS webhook delivery. These are a separate
+integration from a local stdio protocol upgrade. No background monitoring,
+remote endpoint or GUI bridge is enabled by upgrading.
+
+### Object selection
+
+Scene inspection now resolves native KeyShot object IDs into names, materials and
+unique `objectPath` values. Use the returned path when multiple objects share a
+name. Inspect again after renaming or reorganizing objects. Material changes
+continue to save an output scene rather than modifying the source file in place.
+
+## 0.13.0：MCP 协议升级
+
+KeyShot MCP 0.13.0 使用官方 TypeScript SDK v2 的 `serveStdio` 入口，通过 stdio
+支持 MCP `2026-07-28`。同一入口仍接受使用 `2025-11-25` 握手的旧客户端。
+安装配置为 `npx -y keyshot-mcp@0.13.0`，沿用原有 KeyShot 和输出目录环境变量。
+
+1. 将 MCP 客户端配置中的包版本更新到 0.13.0。
+2. 重启 MCP 服务或客户端，以加载新版本。
+3. 运行 `keyshot_status`，检查已保存场景，再请求预览。
+
+19 个工具、产品渲染 Prompt 和工作流 Resource 均保留。结果继续提供 JSON 文本、
+结构化数据和预览图片。本地输出安全限制及已保存场景工作流保持兼容，要求 Node.js 20
+或更高版本。
+
+自动测试使用锁定 `2026-07-28` 的 SDK v2 客户端，以及真正的 SDK v1 客户端连接构建后
+的 stdio 服务。测试验证协议路径，不代表所有第三方客户端的安装和界面行为均已实测。
+
+### MCP Events 事件订阅
+
+本版不声明 `events` 能力，也未实现 ChatGPT 事件订阅。
+[OpenAI 官方接入要求](https://developers.openai.com/plugins/build/mcp-events)还包括经过认证的
+连接、事件发现与订阅接口、持久化订阅和签名 HTTPS webhook 投递。这是后续需要单独
+实现的集成。升级本地协议不会自动开启后台监控、远程接口或 GUI 实时桥接。
+
+### 对象选择
+
+场景检查现在能将 KeyShot 原生对象 ID 解析为名称、材质和唯一的 `objectPath`。
+遇到同名对象时，应使用检查结果中的路径；重命名或调整对象层级后，应重新读取场景。
+材质修改继续保存到输出场景，避免直接改写原文件。

package/lhm.plugin.json

@@ -2386,5 +2386,5 @@
       }
     }
   ],
-  "version": "0.12.0"
+  "version": "0.13.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local MCP server for KeyShot product visualization, scene editing, camera control, and rendering.",
   "type": "module",
@@ -20,7 +20,7 @@
     "prepare": "pnpm run build",
     "start": "node ./dist/index.js",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
+    "test": "pnpm run build && vitest run",
     "docs:tools": "pnpm run build && node ./scripts/generate-tools-docs.mjs",
     "docs:tools:check": "pnpm run build && node ./scripts/generate-tools-docs.mjs --check",
     "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/*.mjs\" \"*.json\" \"*.md\" \"docs/**/*.md\" \"skills/**/*.md\"",
@@ -72,13 +72,16 @@
   },
   "packageManager": "pnpm@10.17.1",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.18.1",
-    "zod": "^3.25.76"
+    "@modelcontextprotocol/core": "2.2.0",
+    "@modelcontextprotocol/server": "2.2.0",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.2.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@types/node": "^22.17.2",
     "prettier": "3.6.2",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   }
 }

package/scripts/keyshot_bridge.py

@@ -85,7 +85,7 @@ def status():
 
 
 def inspect_scene():
-    objects = [describe_object(obj) for obj in safe_list_call("getObjects")]
+    objects = [dict(describe_object(obj), path=path) for obj, path in scene_objects()]
     cameras = [serialize_value(camera) for camera in safe_list_call("getCameras")]
     model_sets = [serialize_value(model_set) for model_set in safe_list_call("getModelSets")]
     environments = [serialize_value(environment) for environment in safe_list_call("getEnvironments")]
@@ -584,11 +584,12 @@ def apply_material_current(payload, warnings):
         raise RuntimeError("Object not found. Provide a valid objectName or objectPath.")
 
     material = resolve_material(payload.get("materialName"), payload.get("materialPath"), warnings)
-    call_variants(
+    target_id = first_success(lambda: target.getID(), default=None)
+    call_non_false_variants(
         "set object material",
-        lambda: lux.setObjectMaterial(target, material),
-        lambda: lux.setObjectMaterial(target, payload.get("materialName")),
-        lambda: lux.setObjectMaterial(target, payload.get("materialPath")),
+        lambda: lux.setObjectMaterial(mat=material, obj=target_id if target_id is not None else target),
+        lambda: (lux.setObjectMaterial(material, target_id) if target_id is not None
+                 else lux.setObjectMaterial(target, material)),
     )
 
     return {
@@ -873,11 +874,49 @@ def safe_list_call(name):
         return [value]
 
 
+def scene_objects():
+    raw = safe_list_call("getObjects")
+    if not raw:
+        return []
+    # Older wrappers expose node objects; native KeyShot returns integer IDs.
+    if all(not isinstance(obj, int) for obj in raw):
+        return [(obj, describe_object(obj)["path"]) for obj in raw]
+    root = first_non_none(lambda: lux.getSceneTree())
+    if root is None:
+        raise RuntimeError("Scene inspection is unsupported: getSceneTree is required to resolve object IDs.")
+    wanted = set(raw)
+    found = {}
+    stack = [(root, "")]
+    visited = set()
+    while stack:
+        node, path = stack.pop()
+        node_id = node.getID()
+        if node_id in visited:
+            continue
+        visited.add(node_id)
+        if node_id in wanted:
+            found[node_id] = (node, path)
+        children = first_success(lambda: node.getChildren(), default=[]) or []
+        entries = []
+        occurrences = {}
+        for child in children:
+            name = str(child.getName()).replace("%", "%25").replace("/", "%2F")
+            name = name.replace("[", "%5B").replace("]", "%5D")
+            occurrences[name] = occurrences.get(name, 0) + 1
+            # Native IDs can change across headless launches; paths use sibling order.
+            entries.append((child, "%s/%s[%s]" % (path, name, occurrences[name])))
+        stack.extend(reversed(entries))
+    missing = wanted.difference(found)
+    if missing:
+        raise RuntimeError("Scene inspection could not resolve object IDs: %s" % sorted(missing))
+    return [found[node_id] for node_id in raw]
+
+
 def describe_object(obj):
     return {
         "name": first_success(lambda: obj.getName(), lambda: obj.name(), lambda: obj.name, default=repr(obj)),
         "path": first_success(lambda: obj.getPath(), lambda: obj.path(), lambda: obj.path, default=None),
-        "type": first_success(lambda: obj.getType(), lambda: obj.type(), lambda: obj.type, default=type(obj).__name__),
+        "type": first_success(lambda: obj.getKind(), lambda: obj.getType(), lambda: obj.type(), lambda: obj.type, default=type(obj).__name__),
         "material": serialize_value(
             first_success(lambda: obj.getMaterial(), lambda: obj.material(), lambda: obj.material, default=None)
         ),
@@ -886,13 +925,13 @@ def describe_object(obj):
 
 
 def find_object(name, path):
-    for obj in safe_list_call("getObjects"):
-        description = describe_object(obj)
-        if name and description.get("name") == name:
-            return obj
-        if path and description.get("path") == path:
-            return obj
-    return None
+    matches = []
+    for obj, object_path in scene_objects():
+        if (path and object_path == path) or (not path and name and describe_object(obj)["name"] == name):
+            matches.append(obj)
+    if len(matches) > 1:
+        raise RuntimeError("Ambiguous object name. Inspect the scene and provide a unique objectPath.")
+    return matches[0] if matches else None
 
 
 def resolve_material(material_name, material_path, warnings):

package/server.json

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

package/skills/keyshot-mcp/SKILL.md

@@ -2,7 +2,7 @@
 name: keyshot-mcp
 author: truman-t3
 description: Install, diagnose, and safely use KeyShot MCP for local product visualization, scene editing, camera control, material assignment, and rendering.
-version: 0.12.0
+version: 0.13.0
 ---
 
 # KeyShot MCP
@@ -35,7 +35,7 @@ Respond in the user's language and explain errors in plain, non-technical terms.
 1. Confirm Node.js 20 or newer is available.
 2. Confirm KeyShot is installed and locally licensed.
 3. Locate `keyshot_headless.exe`. Prefer its absolute path.
-4. Configure the MCP client to run `npx -y keyshot-mcp@0.12.0` and set
+4. Configure the MCP client to run `npx -y keyshot-mcp@0.13.0` and set
    `KEYSHOT_HEADLESS_EXE`.
 5. Leave `KEYSHOT_OUTPUT_DIR` unset to use
    `<home>/Documents/KeyShot MCP Outputs`, or set a user-approved directory.
@@ -50,7 +50,7 @@ Example configuration:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.12.0"],
+      "args": ["-y", "keyshot-mcp@0.13.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -104,11 +104,15 @@ Every tool returns `ok`, operation-specific `data`, `outputFiles`, `warnings`,
 ## Recommended feedback loop
 
 1. Run `keyshot_status`.
-2. Inspect the scene and identify the intended camera or object.
+2. For a model input, import it to a scene copy first. Inspect the saved scene and identify the intended camera or object.
 3. Call `keyshot_preview_render` and describe only what is visible in the returned image.
-4. Ask the user to confirm material, camera, and environment changes.
+4. For proposed changes, state the visible issue, target, exact parameters, and expected effect. Obtain approval for new design decisions; reuse explicit approval already given.
 5. Apply approved edits to a scene copy.
-6. Render at `standard` or `final` quality.
+6. Preview the returned scene copy again and compare it with the approved goal. Do not infer visual success from a file path alone. If image content is unavailable, explain that limitation.
+7. Render the approved scene at `standard` or `final` quality. Stop rather than making unsolicited iterative adjustments.
+
+Model comparison tasks and a reusable evaluation record are in
+[`docs/MODEL-EVALUATION.md`](../../docs/MODEL-EVALUATION.md).
 
 ## Boundaries