keyshot-mcp 0.6.0 → 0.7.0

package/README.md

@@ -1,705 +1,521 @@
 # KeyShot MCP
 
-[![MCP Badge](https://lobehub.com/badge/mcp/truman-t3-keyshot-mcp)](https://lobehub.com/mcp/truman-t3-keyshot-mcp)
-[![GitHub Release](https://img.shields.io/github/v/release/truman-t3/keyshot-mcp)](https://github.com/truman-t3/keyshot-mcp/releases)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/keyshot-mcp.svg)](https://www.npmjs.com/package/keyshot-mcp)
+[![CI](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-English | [中文](#中文说明)
+[English](#english) | [中文](#中文)
 
-A local MCP server for controlling KeyShot Studio through KeyShot headless scripting.
+KeyShot MCP is a local [Model Context Protocol](https://modelcontextprotocol.io/)
+server for inspecting, editing, and rendering KeyShot scenes through KeyShot
+headless scripting. It lets an MCP-compatible AI agent perform repeatable product
+visualization tasks while scenes, models, licenses, and rendered files remain on
+the local computer.
 
-It lets an AI app that supports MCP ask KeyShot to inspect scenes, render images, import models, change materials, adjust cameras, set environments, and save scenes.
+![KeyShot MCP workflow](assets/workflow.svg)
 
-Optimized for Windows-based KeyShot Studio product visualization workflows.
+## English
 
-Unlike GUI-only automation scripts, this project targets KeyShot headless workflows and keeps a stable MCP interface for AI agents.
+### What it can do
 
-## Who This Is For
+- Inspect scene objects, materials, cameras, model sets, and external references.
+- Import models and optionally center them, place them on the ground, update the
+  camera target, and adjust the environment.
+- Render one camera, selected cameras, every camera in a scene, or a sequential
+  render queue.
+- Create and update cameras by position, look-at point, distance, field of view,
+  focal length, or reusable presets.
+- Apply materials directly or through a local material preset library.
+- Select environments, change brightness, and rotate the active environment.
+- Save edited scenes to a controlled output directory.
 
-- Designers who want AI-assisted KeyShot rendering.
-- Developers who want a simple stdio MCP bridge for KeyShot.
-- Teams that already have KeyShot licenses configured on their machines.
+### Requirements and compatibility
 
-This project does not include KeyShot, does not bypass licensing, and does not store license keys.
-
-## What It Can Do
-
-- Check whether KeyShot headless can start.
-- 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.
-
-## Example Workflows
-
-- Batch render multiple camera views from one KeyShot scene.
-- Test several material options on the same product model.
-- Generate product hero images with consistent resolution and output naming.
-- Import a model, apply a material preset, set a camera, and render in one AI instruction.
-
-## Workflow
-
-![KeyShot MCP Workflow](assets/workflow.svg)
-
-## Requirements
-
-- KeyShot Studio with `keyshot_headless` support.
 - Node.js 20 or newer.
-- A valid KeyShot license already configured on the computer.
-
-## Compatibility
-
-| Platform | KeyShot Version | Node Version | Status |
-| --- | --- | --- | --- |
-| Windows 11 | KeyShot Studio 2025 / 14.1 | Node 22 | Tested |
-| macOS | Not tested | - | Need contributors |
-| Linux | Not tested | - | Need contributors |
-
-## Install
-
-### Install the published npm package
-
-```bash
-npm install -g keyshot-mcp
-```
-
-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.
-
-### Install from source
-
-```bash
-npm install
-npm run build
-```
+- A locally installed and licensed KeyShot version with headless scripting.
+- Windows 11 with KeyShot Studio 2025 / KeyShot 14.1 is tested.
+- Other KeyShot versions may work when they expose the same official scripting
+  APIs, but they are not currently verified by this project.
+- KeyShot and its license are not included.
 
-### Three MCP configuration options
+### Install
 
-Use exactly one of these approaches:
+The current release is `0.7.0`.
 
-**Global npm installation** (`npm install -g keyshot-mcp`):
+#### Option 1: run with npx
 
-```json
-{"mcpServers":{"keyshot":{"command":"keyshot-mcp","env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
-```
-
-**No installation, run with npx**:
-
-```json
-{"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`):
+This requires no global npm installation:
 
 ```json
-{"mcpServers":{"keyshot":{"command":"node","args":["/absolute/path/to/keyshot-mcp/dist/index.js"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
-```
-
-## Copy-Paste Setup Prompt for an Agent
-
-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.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.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.
-
-Do not store license keys or account passwords. Use my existing local KeyShot license configuration.
-```
-
-## Configure
-
-Set the path to your KeyShot headless executable.
-
-Windows PowerShell example:
-
-```powershell
-$env:KEYSHOT_HEADLESS_EXE="C:\Program Files\KeyShot Studio\bin\keyshot_headless.exe"
-```
-
-macOS/Linux shell example:
-
-```bash
-export KEYSHOT_HEADLESS_EXE="/Applications/KeyShot Studio.app/Contents/MacOS/keyshot_headless"
+{
+  "mcpServers": {
+    "keyshot": {
+      "command": "npx",
+      "args": ["-y", "keyshot-mcp@0.7.0"],
+      "env": {
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
+      }
+    }
+  }
+}
 ```
 
-Then test startup:
+#### Option 2: install globally
 
 ```bash
-npm run status
+npm install -g keyshot-mcp@0.7.0
 ```
 
-## MCP Client Example
-
-Add a server like this to your MCP client config:
-
 ```json
 {
   "mcpServers": {
     "keyshot": {
-      "command": "node",
-      "args": ["/absolute/path/to/keyshot-mcp/dist/index.js"],
+      "command": "keyshot-mcp",
       "env": {
-        "KEYSHOT_HEADLESS_EXE": "/absolute/path/to/keyshot_headless"
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
     }
   }
 }
 ```
 
-A generic Codex configuration template is in:
+#### Option 3: run from source
 
-```text
-examples/codex.example.json
+```bash
+git clone https://github.com/truman-t3/keyshot-mcp.git
+cd keyshot-mcp
+pnpm install
+pnpm build
 ```
 
-## Codex Configuration
-
-For Codex, add a `keyshot` MCP server entry to your Codex MCP configuration and point it to the built server file:
+Configure the MCP client to run the absolute path to `dist/index.js`:
 
 ```json
 {
   "mcpServers": {
     "keyshot": {
       "command": "node",
-      "args": ["/absolute/path/to/keyshot-mcp/dist/index.js"],
+      "args": ["C:/absolute/path/to/keyshot-mcp/dist/index.js"],
       "env": {
-        "KEYSHOT_HEADLESS_EXE": "/absolute/path/to/keyshot_headless"
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
     }
   }
 }
 ```
 
-Use `examples/codex.example.json` as a starting point and replace all paths with paths on your own computer.
-
-## Prompt Examples
-
-```text
-Render the current KeyShot scene into three views: front, 45-degree perspective, and top-down. Use 1920x1080 resolution and save the outputs to the configured output folder.
-```
-
-```text
-Import the model file at /path/to/model.step, apply a brushed metal material to the main housing, set a 45-degree camera, and render a product hero image.
-```
+Restart the MCP client after changing its configuration.
 
-```text
-Inspect this KeyShot scene and summarize the available objects, cameras, materials, and renderable outputs.
-```
+### Agent installation prompt
 
-```text
-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.
-```
+The following prompt can be pasted into a coding agent that is allowed to edit
+the MCP client configuration:
 
 ```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.
-```
+Install KeyShot MCP 0.7.0 and configure it in my MCP client.
+
+1. Find the local KeyShot headless executable.
+2. Add an MCP server named "keyshot" that runs:
+   npx -y keyshot-mcp@0.7.0
+3. Set KEYSHOT_HEADLESS_EXE to the executable path.
+4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
+5. Restart or reload the MCP client, then call keyshot_status.
+6. Do not upload or publish any KeyShot scenes, models, renders, or license data.
+```
+
+### Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `KEYSHOT_HEADLESS_EXE` | `keyshot_headless.exe` on Windows | Absolute executable path or a command available on `PATH`. |
+| `KEYSHOT_OUTPUT_DIR` | Package-local `outputs` | Root directory for rendered images and saved scenes. |
+| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | Allows output paths outside `KEYSHOT_OUTPUT_DIR` when explicitly set to `true`. |
+| `KEYSHOT_TIMEOUT_MS` | `600000` | Timeout for one KeyShot headless process. |
+| `KEYSHOT_LICENSE_ARGS` | empty | Optional additional KeyShot launch arguments. |
+| `KEYSHOT_MATERIAL_PRESETS` | Built-in `presets/materials.json` | Path to a user-managed material preset file. |
+| `KEYSHOT_CAMERA_PRESETS` | Built-in `presets/cameras.json` | Path to a user-managed camera preset file. |
+
+Relative output paths are resolved inside `KEYSHOT_OUTPUT_DIR`. Parent traversal,
+adjacent-prefix paths, and symbolic-link escapes are rejected by default. Input
+scene, model, material, and environment paths may be located elsewhere.
+
+### Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `keyshot_status` | Verify that KeyShot headless can start and report its version. |
+| `keyshot_inspect_scene` | Inspect objects, cameras, materials, model sets, and references. |
+| `keyshot_list_cameras` | List available camera names. |
+| `keyshot_render` | Render one image. |
+| `keyshot_render_queue` | Run independent render jobs sequentially. |
+| `keyshot_batch_render` | Render a supplied list of named cameras from one scene. |
+| `keyshot_render_all_cameras` | Discover and render every camera in one scene. |
+| `keyshot_import_model` | Import a model with optional composition adjustments. |
+| `keyshot_apply_material` | Apply a library material or material file. |
+| `keyshot_list_material_presets` | List local material presets. |
+| `keyshot_apply_material_preset` | Apply a named material preset. |
+| `keyshot_set_camera` | Create or update camera transform, distance, FOV, or focal length. |
+| `keyshot_list_camera_presets` | List standard and custom camera presets. |
+| `keyshot_apply_camera_preset` | Apply a standard or absolute-coordinate camera preset. |
+| `keyshot_set_environment` | Select or adjust an environment, brightness, or rotation. |
+| `keyshot_save_scene` | Save a scene to a new output path. |
+
+The server also exposes a `keyshot_product_render` MCP prompt and a
+`keyshot://workflow` resource.
+
+### Product composition examples
+
+Import a model and prepare its initial composition:
 
 ```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.
+Import C:\models\speaker.obj into KeyShot. Center the geometry, place it on the
+ground, update the camera look-at point and environment, then save the scene as
+speaker-prepared.bip.
 ```
 
-## Environment Variables
-
-- `KEYSHOT_HEADLESS_EXE`: path to `keyshot_headless` or `keyshot_headless.exe`.
-- `KEYSHOT_OUTPUT_DIR`: default output folder for renders.
-- `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
-an external output location is intentional; input scenes and models are unrestricted.
-
-`samples` and `maxTimeSeconds` select different KeyShot render modes. Provide one
-or the other, not both.
-
-## MCP Tools
-
-- `keyshot_status`
-- `keyshot_inspect_scene`
-- `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
-looks instead of remembering exact KeyShot material names. Default location:
-`presets/materials.json` (override with the `KEYSHOT_MATERIAL_PRESETS` env var).
+The corresponding `keyshot_import_model` options are:
 
 ```json
 {
-  "Brushed Steel": { "materialName": "Steel Brushed", "description": "metal parts" },
-  "Clear Glass": { "materialPath": "C:/materials/glass_clear.mtl" }
+  "centerGeometry": true,
+  "snapToGround": true,
+  "adjustCameraLookAt": true,
+  "adjustEnvironment": true
 }
 ```
 
-Each preset must have a `materialName` or a `materialPath`. Use
-`keyshot_list_material_presets` to see what is available.
-
-### Camera preset library
+Create a product camera with one lens control:
 
-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"
-  }
-}
+```text
+Set the Product Hero camera to a 55 mm focal length and distance 6, save a new
+scene, then render a PNG preview.
 ```
 
-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
+`fieldOfView` must be greater than `0` and less than `180`. `focalLength` accepts
+`5` to `200` mm. The two controls are mutually exclusive. `position` and
+`lookAt` are optional, but must be supplied together when changing the transform.
 
-- Prompt: `keyshot_product_render`
-- Resource: `keyshot://workflow`
+Rotate the active HDRI or environment:
 
-Each tool returns JSON with:
-
-- `ok`
-- `data`
-- `outputFiles`
-- `warnings`
-- `keyshotStdoutTail`
-- `error`
+```text
+Rotate the current KeyShot environment to 45 degrees, save the edited scene,
+and render all cameras.
+```
 
-## Notes
+`rotation` accepts values from `0` inclusive to `360` exclusive.
 
-KeyShot's Python `lux` API changes across versions. This server keeps the MCP interface stable and returns a clear error when an installed KeyShot version does not expose a requested headless function.
+For rendering, `samples` and `maxTimeSeconds` select different KeyShot render
+modes and cannot be supplied together.
 
-## Roadmap
+### Camera and material presets
 
-- [x] Auto-discover and batch render all cameras in a scene
-- [x] Material preset library
-- [x] Camera preset templates
-- [x] Sequential render queue
-- [x] Safer output directory restrictions
-- [ ] More tested KeyShot versions
-- [ ] macOS compatibility verification
-- [x] Claude Desktop / Cursor / Codex config examples
+The built-in camera library includes Front, Back, Left, Right, Top, Bottom, and
+Isometric views. A custom `KEYSHOT_CAMERA_PRESETS` JSON file may contain standard
+views or absolute `position`, `lookAt`, and optional `up` vectors.
 
-## Real KeyShot demo
+Material presets are stored in JSON and reference KeyShot library material names
+or local material files. The MCP server reads preset files but does not modify
+them.
 
-![KeyShot MCP generated cube demo](assets/demo/keyshot-mcp-demo.png)
+### Reproducible KeyShot smoke test
 
-The demo uses only the generated geometry in `examples/demo`. To reproduce the
-status, import, inspect, two-camera creation, save, discovery, and PNG-render workflow locally:
+The repository includes a smoke test built from generated cube geometry in
+`examples/demo`. It verifies startup, import composition, scene inspection,
+camera presets, focal length, field of view, camera distance, environment
+rotation, scene saving, camera discovery, and real PNG rendering:
 
 ```bash
 npm run smoke:keyshot
 ```
 
-## License
-
-MIT
-
----
-
-# 中文说明
-
-[English](#keyshot-mcp) | 中文
-
-这是一个本地 KeyShot MCP 服务，可以让支持 MCP 的 AI 工具通过 KeyShot 的无界面脚本能力控制 KeyShot Studio。
-
-简单说：你可以让 AI 帮你检查 KeyShot 场景、渲染图片、导入模型、替换材质、调整相机、设置环境并保存场景。
-
-本项目优先面向 Windows 环境下的 KeyShot Studio 产品渲染自动化流程。
-
-与仅面向界面操作的自动化脚本不同，本项目优先面向 KeyShot 无界面工作流，并为 AI Agent 提供稳定的 MCP 工具接口。
-
-## 适合谁使用
-
-- 希望用 AI 辅助 KeyShot 渲染的设计师。
-- 想要 KeyShot MCP 桥接工具的开发者。
-- 已经在电脑上配置好 KeyShot 授权的团队。
-
-这个项目不包含 KeyShot，不绕过 KeyShot 授权，也不会保存许可证密钥。
-
-## 能做什么
-
-- 检查 KeyShot 无界面程序是否能启动。
-- 检查 `.bip` 或 KeyShot 支持的场景文件。
-- 把场景渲染成图片。
-- 从同一个场景批量渲染多个指定相机。
-- 自动发现并渲染场景中的全部相机。
-- 把模型导入场景。
-- 给对象替换材质。
-- 创建或更新相机。
-- 应用可复用的标准或自定义相机预设。
-- 在当前 KeyShot 版本支持时设置环境。
-- 把场景保存为新文件。
-
-## 典型使用场景
-
-- 批量渲染同一个 KeyShot 场景的多个相机视角。
-- 对同一个产品模型快速测试多组材质方案。
-- 统一输出产品首图、封面图、详情页渲染图。
-- 用一句自然语言完成导入模型、替换材质、设置相机、渲染出图。
-
-## 工作流程
-
-![KeyShot MCP Workflow](assets/workflow.svg)
-
-## 使用要求
+Generated `.bip` files and test renders remain in the configured local output
+directory. The repository includes one representative result:
 
-- 已安装支持 `keyshot_headless` 的 KeyShot Studio。
-- Node.js 20 或更新版本。
-- 电脑上已经配置好有效的 KeyShot 授权。
+![KeyShot smoke test render](assets/demo/keyshot-mcp-demo.png)
 
-## 版本兼容表
-
-| 平台 | KeyShot 版本 | Node 版本 | 状态 |
-| --- | --- | --- | --- |
-| Windows 11 | KeyShot Studio 2025 / 14.1 | Node 22 | 已测试 |
-| macOS | 未测试 | - | 需要贡献者 |
-| Linux | 未测试 | - | 需要贡献者 |
-
-## 安装
-
-### 安装已发布的 npm 包
+### Development and tests
 
 ```bash
-npm install -g keyshot-mcp
+pnpm install
+pnpm check
+pnpm test
+python -m unittest discover -s tests -p "test_*.py"
+npm pack --dry-run
 ```
 
-当前发布版本为 `0.6.0`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
-电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
-
-### 从源码安装
-
-```bash
-npm install
-npm run build
-```
+CI runs on Windows and Ubuntu with Node.js 20 and 24. Linux CI validates the MCP
+server, bridge logic, and package; it does not claim that KeyShot itself runs on
+Linux.
 
-### 三种独立配置方式
+### Roadmap
 
-下面三种方式选择一种即可：
+- Verify additional KeyShot releases on real installations.
+- Verify macOS installation and headless behavior.
+- Add depth-of-field and additional lens controls when stable headless APIs are
+  available.
 
-**全局 npm 安装**（先运行 `npm install -g keyshot-mcp`）：
+### Star history
 
-```json
-{"mcpServers":{"keyshot":{"command":"keyshot-mcp","env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
-```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="assets/star-history-light.svg">
+  <img alt="GitHub star history for truman-t3/keyshot-mcp" src="assets/star-history-light.svg">
+</picture>
 
-**免安装，直接使用 npx**：
+The chart uses the actual `starred_at` date for each GitHub star and displays a
+cumulative step line. A weekly GitHub Action updates it only when detailed
+stargazer dates are available.
 
-```json
-{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.6.0"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
-```
+### License and security
 
-**使用本地源码**（先运行 `npm install && npm run build`）：
+Released under the [MIT License](LICENSE). See [SECURITY.md](SECURITY.md) for
+security guidance and [CONTRIBUTING.md](CONTRIBUTING.md) for development notes.
+Do not commit KeyShot licenses, private scenes, customer assets, or unpublished
+renders.
 
-```json
-{"mcpServers":{"keyshot":{"command":"node","args":["C:/path/to/keyshot-mcp/dist/index.js"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
-```
+---
 
-## 复制给 Agent 的安装提示词
+## 中文
 
-如果你使用 Codex 或其他编程 Agent，可以复制下面这段话，让 Agent 帮你安装和配置 MCP：
+KeyShot MCP 是一个本地运行的
+[Model Context Protocol](https://modelcontextprotocol.io/) 服务，通过 KeyShot
+headless 脚本让兼容 MCP 的 AI Agent 检查、编辑和渲染 KeyShot 场景。场景、模型、
+许可证和渲染文件均保留在本机。
 
-```text
-请帮我安装 KeyShot MCP 0.6.0，并添加到我的 MCP 客户端。
+### 主要功能
 
-请你：
-1. 查找我电脑上的 KeyShot headless 可执行文件路径。
-2. 使用 npx -y keyshot-mcp@0.6.0 添加 keyshot MCP server。
-3. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
-4. 用 keyshot_status 工具测试是否配置成功。
-5. 最后告诉我实际添加的配置，以及状态检查是否通过。
+- 检查场景对象、材质、相机、模型集和外部引用。
+- 导入模型，并可选择自动居中、贴地、调整相机观察点和环境。
+- 渲染单个相机、指定相机、场景中的全部相机或顺序渲染队列。
+- 通过位置、观察点、距离、视野角、焦距或预设创建和更新相机。
+- 直接应用材质，或使用本地材质预设库。
+- 选择环境、调整亮度并旋转当前环境。
+- 将修改后的场景保存到受控输出目录。
 
-不要保存许可证密钥、账号密码或授权信息。直接使用我电脑上已有的 KeyShot 本地授权配置。
-```
+### 运行要求与兼容性
 
-## 配置
+- Node.js 20 或更高版本。
+- 本机已安装并获得许可、且支持 headless 脚本的 KeyShot。
+- 已实测：Windows 11、KeyShot Studio 2025 / KeyShot 14.1。
+- 其他 KeyShot 版本在提供相同官方脚本 API 时可能兼容，但本项目尚未完成实机验证。
+- 本项目不包含 KeyShot 软件或许可证。
 
-需要告诉 MCP 服务 KeyShot 无界面程序在哪里。
+### 安装
 
-Windows PowerShell 示例：
+当前版本为 `0.7.0`。
 
-```powershell
-$env:KEYSHOT_HEADLESS_EXE="C:\Program Files\KeyShot Studio\bin\keyshot_headless.exe"
-```
+#### 方式一：使用 npx
 
-macOS/Linux 示例：
+无需全局安装 npm 包：
 
-```bash
-export KEYSHOT_HEADLESS_EXE="/Applications/KeyShot Studio.app/Contents/MacOS/keyshot_headless"
+```json
+{
+  "mcpServers": {
+    "keyshot": {
+      "command": "npx",
+      "args": ["-y", "keyshot-mcp@0.7.0"],
+      "env": {
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
+      }
+    }
+  }
+}
 ```
 
-然后测试能否启动：
+#### 方式二：全局安装
 
 ```bash
-npm run status
+npm install -g keyshot-mcp@0.7.0
 ```
 
-## MCP 客户端配置示例
-
-把类似下面的配置加到你的 MCP 客户端里：
-
 ```json
 {
   "mcpServers": {
     "keyshot": {
-      "command": "node",
-      "args": ["/absolute/path/to/keyshot-mcp/dist/index.js"],
+      "command": "keyshot-mcp",
       "env": {
-        "KEYSHOT_HEADLESS_EXE": "/absolute/path/to/keyshot_headless"
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
     }
   }
 }
 ```
 
-通用 Codex 配置模板在：
+#### 方式三：从源码运行
 
-```text
-examples/codex.example.json
+```bash
+git clone https://github.com/truman-t3/keyshot-mcp.git
+cd keyshot-mcp
+pnpm install
+pnpm build
 ```
 
-## Codex 配置
-
-如果你使用 Codex，请在 Codex 的 MCP 配置里添加一个 `keyshot` 服务，并指向构建后的服务文件：
+将 MCP 客户端配置为运行 `dist/index.js` 的绝对路径：
 
 ```json
 {
   "mcpServers": {
     "keyshot": {
       "command": "node",
-      "args": ["/absolute/path/to/keyshot-mcp/dist/index.js"],
+      "args": ["C:/absolute/path/to/keyshot-mcp/dist/index.js"],
       "env": {
-        "KEYSHOT_HEADLESS_EXE": "/absolute/path/to/keyshot_headless"
+        "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
     }
   }
 }
 ```
 
-`examples/codex.example.json` 是通用配置模板。使用时请把里面的路径换成自己电脑上的路径。
+修改配置后请重启或重新加载 MCP 客户端。
 
-## 提示词示例
+### 复制给 Agent 的安装提示词
 
-```text
-把当前 KeyShot 场景渲染成三个视角：正视图、45 度透视图和俯视图。分辨率为 1920x1080，并保存到默认输出文件夹。
-```
+下面的提示词适用于有权限修改 MCP 客户端配置的编程 Agent：
 
 ```text
-导入 /path/to/model.step，给主体外壳应用拉丝金属材质，设置 45 度相机，并渲染一张产品主视觉图。
-```
+请帮我安装 KeyShot MCP 0.7.0，并添加到我的 MCP 客户端。
+
+1. 查找本机 KeyShot headless 可执行文件。
+2. 添加名为 keyshot 的 MCP server，运行：
+   npx -y keyshot-mcp@0.7.0
+3. 将 KEYSHOT_HEADLESS_EXE 设置为可执行文件路径。
+4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
+5. 重启或重新加载 MCP 客户端，然后调用 keyshot_status。
+6. 不要上传或发布任何 KeyShot 场景、模型、渲染图或许可证数据。
+```
+
+### 配置项
+
+| 环境变量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `KEYSHOT_HEADLESS_EXE` | Windows 上为 `keyshot_headless.exe` | KeyShot headless 绝对路径，或系统 `PATH` 中的命令。 |
+| `KEYSHOT_OUTPUT_DIR` | 包内 `outputs` | 渲染图和已保存场景的根目录。 |
+| `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` | `false` | 明确设为 `true` 时允许写入输出根目录之外。 |
+| `KEYSHOT_TIMEOUT_MS` | `600000` | 单个 KeyShot headless 进程的超时时间。 |
+| `KEYSHOT_LICENSE_ARGS` | 空 | 可选的 KeyShot 启动参数。 |
+| `KEYSHOT_MATERIAL_PRESETS` | 内置 `presets/materials.json` | 自定义材质预设 JSON 路径。 |
+| `KEYSHOT_CAMERA_PRESETS` | 内置 `presets/cameras.json` | 自定义相机预设 JSON 路径。 |
+
+相对输出路径会自动放入 `KEYSHOT_OUTPUT_DIR`。默认拒绝 `..`、相邻同名前缀目录和
+软链接逃逸。输入场景、模型、材质和环境文件可位于其他目录。
+
+### MCP 工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `keyshot_status` | 检查 KeyShot headless 是否可启动并读取版本。 |
+| `keyshot_inspect_scene` | 检查对象、相机、材质、模型集和外部引用。 |
+| `keyshot_list_cameras` | 列出场景中的相机名称。 |
+| `keyshot_render` | 渲染一张图片。 |
+| `keyshot_render_queue` | 顺序执行多个独立渲染任务。 |
+| `keyshot_batch_render` | 渲染用户指定的一组相机。 |
+| `keyshot_render_all_cameras` | 自动发现并渲染场景中的全部相机。 |
+| `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_product_render` MCP 提示词和 `keyshot://workflow` 资源。
+
+### 产品构图示例
+
+导入模型并完成初始构图：
 
 ```text
-检查当前 KeyShot 场景，并总结场景中的对象、相机、材质和可渲染输出。
+把 C:\models\speaker.obj 导入 KeyShot，自动居中、贴地、调整相机观察点和环境，
+然后保存为 speaker-prepared.bip。
 ```
 
-```text
-列出当前 KeyShot 场景中的相机，创建或更新一个名为“Hero”的相机，
-把场景保存为新文件，并用这个相机渲染一张预览图。
-```
-
-```text
-自动找出这个 KeyShot 场景里的全部相机，把所有视角渲染到 all-cameras 文件夹。
-某个相机失败时继续处理其他相机，最后告诉我每个视角的结果。
-```
-
-```text
-列出可用的相机预设，把 Isometric 等距预设应用为名为“目录等距视图”的相机，
-保存一份新场景，并用这个相机渲染预览图。
-```
-
-## 环境变量
-
-- `KEYSHOT_HEADLESS_EXE`：`keyshot_headless` 或 `keyshot_headless.exe` 的路径。
-- `KEYSHOT_OUTPUT_DIR`：默认渲染输出文件夹。
-- `KEYSHOT_LICENSE_ARGS`：可选的 KeyShot 无界面许可证参数，默认留空。
-- `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`；输入场景和模型路径不受此限制。
-
-`samples` 和 `maxTimeSeconds` 是两种不同的 KeyShot 渲染模式，请二选一，不要同时传入。
-
-## MCP 工具
-
-- `keyshot_status`：检查 KeyShot 是否能启动。
-- `keyshot_inspect_scene`：检查场景内容。
-- `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 注册表，让你用"好记的名字"复用材质，
-而不必记住 KeyShot 里精确的材质名。默认位置：`presets/materials.json`
-（可用环境变量 `KEYSHOT_MATERIAL_PRESETS` 覆盖）。
+对应的 `keyshot_import_model` 参数：
 
 ```json
 {
-  "拉丝钢": { "materialName": "Steel Brushed", "description": "金属件默认材质" },
-  "透明玻璃": { "materialPath": "C:/materials/glass_clear.mtl" }
+  "centerGeometry": true,
+  "snapToGround": true,
+  "adjustCameraLookAt": true,
+  "adjustEnvironment": true
 }
 ```
 
-每个预设必须包含 `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": "自定义绝对坐标相机"
-  }
-}
+```text
+把 Product Hero 相机设为 55 mm 焦距、距离 6，保存新场景并渲染 PNG 预览图。
 ```
 
-预设文件既可以使用上面的对象格式，也可以使用每项包含 `name` 的数组格式。
-每个预设只能选择一种形式：填写一个受支持的 `standardView`，或者同时填写
-`position` 与 `lookAt`。MCP 只读取预设文件，不会自动修改它。
-
-## MCP 提示词和资源
-
-- 提示词：`keyshot_product_render`
-- 资源：`keyshot://workflow`
+`fieldOfView` 必须大于 `0` 且小于 `180`；`focalLength` 支持 `5–200 mm`，
+两者不能同时使用。`position` 和 `lookAt` 可不填写，但修改相机位置时必须成对提供。
 
-每个工具都会返回 JSON，包含：
+旋转当前 HDRI 或环境：
 
-- `ok`：是否成功。
-- `data`：主要结果。
-- `outputFiles`：生成的文件。
-- `warnings`：警告信息。
-- `keyshotStdoutTail`：KeyShot 输出摘要。
-- `error`：错误信息。
+```text
+把当前 KeyShot 环境旋转到 45 度，保存场景，然后渲染全部相机。
+```
 
-## 说明
+`rotation` 支持大于等于 `0` 且小于 `360` 的数值。
 
-KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对外工具名称稳定；如果当前 KeyShot 版本不支持某个无界面功能，会返回明确错误，而不是假装成功。
+渲染参数 `samples` 和 `maxTimeSeconds` 对应不同的 KeyShot 渲染模式，不能同时使用。
 
-## 路线图
+### 相机与材质预设
 
-- [x] 自动发现并批量渲染场景中的所有相机
-- [x] 材质预设库
-- [x] 相机预设模板
-- [x] 顺序渲染队列
-- [x] 更安全的输出目录限制
-- [ ] 测试更多 KeyShot 版本
-- [ ] 验证 macOS 兼容性
-- [x] 补充 Claude Desktop / Cursor / Codex 配置示例
+内置相机库包含 Front、Back、Left、Right、Top、Bottom 和 Isometric 七个标准视角。
+自定义 `KEYSHOT_CAMERA_PRESETS` JSON 可使用标准视角，也可提供绝对 `position`、
+`lookAt` 和可选 `up` 向量。
 
-## 真实 KeyShot Demo
+材质预设通过 JSON 引用 KeyShot 材质库名称或本地材质文件。MCP 只读取预设文件，
+不会自动修改它们。
 
-![KeyShot MCP 自动生成的立方体 Demo](assets/demo/keyshot-mcp-demo.png)
+### 可复现的 KeyShot smoke test
 
-Demo 只使用 `examples/demo` 中项目自己生成的几何体，不包含客户模型或第三方素材。
-设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建两个相机、自动发现、保存和真实 PNG 渲染：
+仓库提供基于 `examples/demo` 生成立方体几何体的 smoke test，用于验证 KeyShot
+启动、导入构图、场景检查、相机预设、焦距、视野角、相机距离、环境旋转、场景保存、
+相机发现和真实 PNG 渲染：
 
 ```bash
 npm run smoke:keyshot
 ```
 
-## 测试
+生成的 `.bip` 和测试渲染图只保留在配置的本地输出目录。仓库中包含一张代表性结果：
 
-项目带了两套测试，不依赖真实的 KeyShot 也能跑：
+![KeyShot smoke test 渲染图](assets/demo/keyshot-mcp-demo.png)
 
-- **TypeScript 测试（Vitest）**：覆盖配置读取、参数校验（schemas）、结果封装，以及用"假 KeyShot"跑通一次成功路径并验证 `work/tmp` 临时文件会被清理。
+### 开发与测试
 
-  ```bash
-  npm install
-  npm test
-  ```
+```bash
+pnpm install
+pnpm check
+pnpm test
+python -m unittest discover -s tests -p "test_*.py"
+npm pack --dry-run
+```
 
-- **Python bridge 测试（unittest）**：用假的 `lux` 对象验证 `import_model` 会真正打开基础场景、`set_camera` 在拿不到相机对象时不会崩溃并回退到 `lux` 级 API。
+CI 在 Windows 和 Ubuntu 上使用 Node.js 20、24 运行。Linux CI 验证 MCP 服务、
+桥接逻辑和 npm 包，不代表 KeyShot 软件已在 Linux 上通过实机测试。
 
-  ```bash
-  python tests/test_bridge.py
-  ```
+### 路线图
 
-## 开源协议
+- 在更多 KeyShot 正式版本上完成实机验证。
+- 验证 macOS 安装和 headless 行为。
+- 在 headless API 稳定支持后增加景深和更多镜头控制。
 
-MIT
+### 星标趋势
 
-## Star History / 星标趋势
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="assets/star-history-light.svg">
+  <img alt="truman-t3/keyshot-mcp 的 GitHub 星标趋势" src="assets/star-history-light.svg">
+</picture>
 
-![Star History Chart](assets/star-history.svg)
+趋势图使用每颗 GitHub Star 的真实 `starred_at` 日期绘制累计阶梯线。GitHub Actions
+每周检查一次，并且只在能够取得逐星日期时更新。
 
-This chart is generated from GitHub stargazer data and refreshed by GitHub Actions.
+### 许可证与安全
 
-这张图由 GitHub star 数据生成，并通过 GitHub Actions 定时刷新。
+项目采用 [MIT License](LICENSE)。安全说明见 [SECURITY.md](SECURITY.md)，开发说明
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。请勿提交 KeyShot 许可证、私有场景、客户素材
+或未公开渲染图。