fnf-blender-mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,47 +1,29 @@
 # Higgsfield use Blender
 
-An independent local MCP project for editing native Blender scenes. No WebSocket, Cloudflare Worker, R2 bucket or cloud bridge account is required.
+The independent `fnf-blender-mcp` package in `fnf-local-pluging-bridge-mcp/blender` controls a dedicated background Blender process. No add-on, HTTP listener, WebSocket, cloud account or open Blender window is required.
 
 ```text
-Desktop MCP client ── stdio ── Node MCP server
-                                  │
-                     authenticated HTTP on 127.0.0.1
-                                  │
-                        Blender Python add-on
-                                  │
-                       main-thread timer → bpy
+Desktop MCP client → stdio → Node MCP → process pipes → Blender --background → bpy
 ```
 
-Install the public [fnf-blender-mcp](https://www.npmjs.com/package/fnf-blender-mcp) package, published by `arsu_higgsfield_ai`. No source checkout or build is needed for installation.
+Each MCP connection owns one process. Its scene persists between commands; it cannot access unsaved work in an already-open desktop Blender. Open saved input with `bl_open_project`, edit and render, then save a `.blend` output to inspect in the desktop UI. Disconnecting loses unsaved session changes. The After Effects package at the repository root is independent.
 
-## Quick start
+## Setup
 
-Requires Node.js 24+ with npm and Blender 4.2+. Blender supplies the add-on's Python runtime; a separate Python installation is only needed for development tests.
-
-Install into a persistent user directory (macOS/Linux):
+Requires Node.js 24+ with npm and Blender 4.2+. Version 0.2.0 introduces the background runtime; version 0.1.0 uses the previous add-on. Install the latest published version (0.2.0 or newer); rerun the install command to update an existing installation.
 
 ```sh
-bridgeDir="$HOME/.higgsfield/blender-mcp"
-npm install --prefix "$bridgeDir" --registry=https://registry.npmjs.org/ fnf-blender-mcp@0.1.0
-bridgeCli="$bridgeDir/node_modules/fnf-blender-mcp/dist/cli.js"
-node "$bridgeCli" launch --blender "/absolute/path/to/blender"
-node "$bridgeCli" doctor
-node "$bridgeCli" config --format json
+npm view fnf-blender-mcp@latest version --registry=https://registry.npmjs.org/
+blenderDir="$HOME/.higgsfield/blender-mcp"
+npm install --prefix "$blenderDir" --registry=https://registry.npmjs.org/ fnf-blender-mcp@latest
+blenderCli="$blenderDir/node_modules/fnf-blender-mcp/dist/cli.js"
+node "$blenderCli" doctor --blender "/absolute/path/to/blender"
+node "$blenderCli" config --blender "/absolute/path/to/blender" --format json
 ```
 
-For Windows PowerShell, use `$bridgeDir = Join-Path $env:LOCALAPPDATA 'Higgsfield/blender-mcp'`, install with `npm.cmd install --prefix $bridgeDir --registry=https://registry.npmjs.org/ fnf-blender-mcp@0.1.0`, then set `$bridgeCli = Join-Path $bridgeDir 'node_modules/fnf-blender-mcp/dist/cli.js'` and invoke `node $bridgeCli` with the commands above. The [installation skill](skills/use-blender/references/installation.md) contains the full setup procedure.
-
-`launch` opens a **new** Blender process with the bundled bridge. It does not attach to an existing process or change saved preferences. Wait for startup before running `doctor`. Use the actual executable, such as `Blender.app/Contents/MacOS/Blender` on macOS or `blender.exe` on Windows.
-
-For an existing installation and automatic startup:
+Use the executable inside `Blender.app/Contents/MacOS/Blender` on macOS, or `blender.exe` on Windows. `config --format toml` prints a Codex entry. Both formats include absolute Node/server paths and `BLENDER_EXECUTABLE`; merge the entry into the intended client and refresh its connection. The helper prints configuration but does not register a server. See the [installation skill](skills/use-blender/references/installation.md) for PowerShell and migration steps.
 
-```sh
-node "$bridgeCli" install-addon --blender "/absolute/path/to/blender"
-```
-
-Enable **Higgsfield use Blender** in Blender's Preferences → Add-ons, then save preferences if desired. The installer only copies the add-on into that version's user scripts directory. It never saves or resets preferences, and refuses to overwrite an unrecognized add-on directory. An already-running instance may need refreshing or restarting; preserve unsaved work.
-
-Merge the generated JSON entry into the desktop client's MCP configuration. For Codex use `node "$bridgeCli" config --format toml`. This helper prints configuration; it does not register or enable a client connection. Both formats use absolute Node and server paths. Keep the installed package at that persistent location. Refresh the client's MCP connection, then call `bl_health` and `bl_get_scene_summary` from the conversation. A shell `doctor` success alone does not establish conversation tool availability.
+The server starts Blender on its first execution call. `doctor` checks a separate temporary background process and terminates it afterward. Verify conversation access with `bl_health` and `bl_get_scene_summary`. `BLENDER_EXECUTABLE` can be set directly; without it the runtime tries standard installation locations and PATH. No separate Python installation is needed at runtime.
 
 ## Tools
 
@@ -52,43 +34,39 @@ Merge the generated JSON entry into the desktop client's MCP configuration. For
 | Camera/light | `bl_add_camera`, `bl_set_active_camera`, `bl_add_light` |
 | Animation | `bl_set_frame`, `bl_insert_keyframe` |
 | Files | `bl_save_project`, `bl_open_project` |
-| Evidence | `bl_screenshot`, `bl_render` |
+| Evidence | `bl_render` |
 | Python/status | `bl_execute`, `bl_job_status` |
-| Offline guidance | `bl_get_skill` |
+| Offline guidance | `bl_list_skills`, `bl_get_skill`, `bl_get_skill_asset` |
 
-Start with `bl_get_skill(name: "blender-scene")`. It routes to modeling, materials, lighting/camera and animation guidance. Use `bl_execute` for bpy operations beyond the typed tools; assign a JSON-compatible value to `result`. stdout and stderr are returned with a 64 KiB cap each. Results are limited to 4 MiB; return a file path for larger data.
+Start with `bl_get_skill(name: "blender-scene")`. Python runs sequentially on the process's main thread. Scene datablocks persist, while script-local variables do not. Assign a JSON-compatible `result` to return data. Python stdout/stderr are capped at 64 Ki characters each; JSON results are limited to 4 MiB. Native Blender diagnostics do not enter the MCP stdout protocol.
 
-Screenshots return inline MCP images without cloud uploads and need a VIEW_3D area. Camera renders write a local PNG and include a preview for files up to 4 MiB. Render overrides are restored afterward; an explicit sample override currently requires Cycles. Saving or rendering over an existing file requires `overwrite: true`. Opening a project refuses unsaved changes unless `discard_unsaved: true`.
+The npm archive contains the Blender craft modules. `bl_list_skills` lists the modules in the installed package and their references/assets; `bl_get_skill` reads an entry or reference, and `bl_get_skill_asset` returns the local path of a bundled file. The original five `bl_get_skill` names remain valid. An MCP client can read this guidance directly without installing the modules as client-side skills; client-side installation is optional for hosts that support automatic skill activation. Existing installations do not gain new modules or tools until the npm package is updated and the MCP connection refreshed. Skill guidance does not execute Blender operations or prove a live connection.
 
-This package does not bundle cloud generation, offline Blender API/manual search, or the original connector's model-generation and motion-import handlers. Use a separate Higgsfield MCP for generation, download finished assets, and import an absolute local path. Local Python has the full permissions of the Blender process; it is not a sandbox.
+Render a camera frame to PNG; files up to 4 MiB receive an inline preview. Cycles supports sample overrides. Save/render require `overwrite: true` for existing output files; opening a different project refuses unsaved changes unless explicitly discarded. Arbitrary Python is not sandboxed and can bypass these typed-tool guards. Automatic execution of Python embedded in opened `.blend` files is disabled.
 
-## Connection and timeout behavior
+## Session lifecycle
 
-- The add-on binds an ephemeral loopback port and generates a random bearer token. Discovery files live in `~/.higgsfield/blender/bridge-<pid>.json`, with owner-only file permissions on POSIX. Windows uses the user's profile-directory ACLs.
-- Browser-origin requests, incorrect Host headers and missing/incorrect tokens are rejected. Do not expose the endpoint or share its token.
-- The server refuses ambiguous multi-instance discovery. Set `BLENDER_MCP_PID` in the MCP server environment to select the intended instance.
-- Override `BLENDER_MCP_RUNTIME_DIR` on **both** the Blender process and MCP process when a custom directory is needed. `config` does not include these environment overrides automatically.
-- HTTP only queues work. A persistent Blender timer executes Python on the main thread. Rendering or long scripts can block Blender's UI.
-- Commands are accepted once and receive a job ID. Pending jobs expire before execution after their deadline. A running script cannot be safely interrupted; timeout does not mean cancellation or rollback.
-- After a timeout, use `bl_job_status` on the original PID before retrying. A script exception can leave partial changes. If submission failed before the job ID was received, inspect the scene first.
-- Up to 128 job records are retained in memory, with old completed jobs evicted as new jobs arrive. Restarting Blender loses history. A client-side MCP timeout may occur before the tool returns its job ID; set tool timeouts above 300 seconds for long renders and inspect state before retrying.
+A timed-out job continues and keeps its `job_id`. Query `bl_job_status` before retrying; additional execution commands are rejected while it runs. No automatic retries or rollbacks occur. Status retains at most 128 jobs within the MCP process. If Blender crashes, the session fails and is not restarted automatically: inspect output files before reconnecting to a new empty session. Closing the MCP terminates its child process, including a running job; save needed changes first.
 
-## Development and verification
+In 0.2.0, `launch`, `install-addon`, `bl_screenshot`, bridge discovery, PID selection and runtime-directory overrides are removed. Use camera renders for visual evidence. No existing desktop scenes, preferences or installed add-ons are modified during startup. Multiple MCP connections have separate background scenes.
 
-From a source checkout, run `npm ci` first. Development checks:
+## Development and validation
+
+From the repository root:
 
 ```sh
+cd blender
+npm ci
 npm test
 npm run typecheck
 npm run test:package
+BLENDER_EXECUTABLE=/absolute/path/to/blender npm run test:live
 ```
 
-The automated tests cover a real stdio MCP subprocess talking to the real Python HTTP bridge, authenticated discovery, multiple instances, execution errors, result images, input validation, queue overload, expiration, timeouts and status recovery. A minimal bpy fixture supplies metadata in those tests. Every typed Python script is syntax-compiled. `test:package` builds a local `.tgz`, installs it in an isolated directory, and checks the shipped runtime, skills and setup files; it does not publish anything.
-
-**These tests do not prove live Blender behavior.** Blender was not found on the development Mac, so real geometry, viewport rendering, installer behavior inside Blender and Windows/Linux integration remain unverified. For a live check, run `doctor`, inspect a disposable scene, create a primitive, set a material and camera, render/view a small PNG, save/reopen a temporary `.blend`, and confirm unsaved-file guards. Never use an existing unsaved project as the test fixture.
+Offline tests exercise actual MCP and child-process pipes using a Python CLI fixture, persistent session state, isolation, timeout recovery, process death, bounded results/history, output formatting, CLI configuration and typed-script guards. They do not replace live Blender validation. `test:package` installs the archive independently and verifies 21 tools, offline guidance, asset lookup and the absence of runtime add-on files. `test:live` uses real Blender for geometry, materials, keyframes, file guards and a small Cycles render in disposable files.
 
-## Slash command
+Verified on macOS arm64 with Blender 4.2.23 LTS: persistent scene, mesh/material/camera/light edits, keyframes, save/reopen guards and a Cycles PNG preview. Windows/Linux native Blender execution has not been verified locally.
 
-The matching `/use-blender` bundle is added to `fnf-mcp-server` under `src/tools/preset-instructions/resources/commands/use-blender`. It returns installation and verification instructions before any remote preset lookup. The standalone source lives in `skills/use-blender`; keep their bodies synchronized when editing setup instructions. The server command adds a `title` frontmatter field for its catalog.
+See [RELEASING.md](RELEASING.md) for release steps. The setup skill is mirrored in fnf-mcp-server's `/use-blender` command; keep its body and references synchronized. See [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for the MIT license.
 
-See [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for the MIT license.
+Background Blender does not reliably mark direct Python edits as dirty. The MCP also tracks attempted mutations, including failed commands and arbitrary `bl_execute` calls, conservatively as unsaved until `bl_save_project` or an explicitly permitted `bl_open_project` succeeds. Read tools preserve this state.

package/RELEASING.md

@@ -0,0 +1,11 @@
+# Release fnf-blender-mcp
+
+Run commands from this `blender/` directory. Its package and lockfile are independent of After Effects.
+
+1. Run `npm ci`, `npm test`, `npm run typecheck`, `npm run test:package`, and `test:live` with a real `BLENDER_EXECUTABLE` when available.
+2. Version 0.2.1 bundles the Blender craft skills, including the additions from PR #25. Verify that it is unpublished with `npm view fnf-blender-mcp versions --json`. Never overwrite an existing npm version; bump both manifests for subsequent releases.
+3. Keep README.md, skills/use-blender and the fnf-mcp-server command bundle on `fnf-blender-mcp@latest`; preserve historical migration versions. Review migration instructions for removed commands and tools.
+4. Merge the source changes and version metadata into `main`, check out its exact commit in a clean worktree, rerun the checks, then run `npm pack --json`, review the contents, then publish the reviewed archive with `npm publish ./fnf-blender-mcp-0.2.1.tgz --access public --registry=https://registry.npmjs.org/` when publication is authorized.
+5. Verify the public version and checksum and test a fresh registry installation. Publish the package before deploying the fnf-mcp-server instructions that require it.
+
+Merging the source MR does not publish npm. Version 0.1.0 still requires the old add-on; it is not a fallback for 0.2.0 setup. New clients need a refreshed configuration containing BLENDER_EXECUTABLE. Existing desktop files and add-ons are not removed by this release.

package/UPSTREAM.md

@@ -1 +1 @@
-Core Blender tool Python bodies and schemas are adapted from Higgsfield fnf-adobe-mcp-connector, worker/bl-tools.ts and worker/bl-schemas.ts, revision fd5359a8c72f6ce30e62e5b500ffaf08f649bb84 (MIT per upstream package.json). Cloud routing, R2 image storage, cloud generation and remote documentation commands are omitted. The local transport, add-on, installer and setup skill are independent implementations.
+Core Blender tool Python bodies and schemas are adapted from Higgsfield fnf-adobe-mcp-connector, worker/bl-tools.ts and worker/bl-schemas.ts, revision fd5359a8c72f6ce30e62e5b500ffaf08f649bb84 (MIT per upstream package.json). Cloud routing, R2 image storage, cloud generation and remote documentation commands are omitted. The background process transport, command runner and setup skill are independent implementations.

package/dist/cli.js

@@ -1,70 +1,58 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { stat } from "node:fs/promises";
-import { isAbsolute } from "node:path";
-import { BlenderTransport, discover } from "./transport.js";
-const root = new URL("../", import.meta.url);
+import { BlenderTransport, resolveExecutable } from "./transport.js";
 const usage = `Higgsfield use Blender
-  fnf-blender doctor                         Discover bridges and verify live bpy execution
-  fnf-blender config [--format json|toml]    Print local MCP configuration
-  fnf-blender launch --blender PATH          Open Blender with the bundled bridge
-  fnf-blender install-addon --blender PATH   Install the add-on for that Blender version
-  fnf-blender serve                          Run the stdio MCP server
+  fnf-blender doctor [--blender PATH]                    Verify a new background Blender process
+  fnf-blender config [--blender PATH] [--format json|toml] Print local MCP configuration
+  fnf-blender serve                                      Run the stdio MCP server
 
-Requires Node.js 24+ and Blender 4.2+. BLENDER_MCP_PID selects an instance.
-BLENDER_MCP_RUNTIME_DIR overrides local bridge discovery on both processes.
-No WebSocket or cloud account is required. npm package: fnf-blender-mcp.`;
+Requires Node.js 24+ and Blender 4.2+. BLENDER_EXECUTABLE selects the executable.
+Each MCP session owns a background Blender process. Save .blend files before reconnecting.
+No add-on, HTTP listener, WebSocket or open Blender window is required.`;
 async function main() {
     const [command = "help", ...args] = process.argv.slice(2);
     if (["help", "--help", "-h"].includes(command)) {
         console.log(usage);
         return;
     }
-    if (command === "serve") {
+    if (command === "serve" && args.length === 0) {
         await import("./index.js");
         return;
     }
-    if (command === "config") {
-        if (args.length && (args[0] !== "--format" || args.length !== 2 || !["json", "toml"].includes(args[1])))
+    if (!["config", "doctor"].includes(command))
+        throw new Error(usage);
+    let executable, format = "json";
+    const seen = new Set();
+    for (let index = 0; index < args.length; index += 2) {
+        const key = args[index], value = args[index + 1];
+        if (!value || seen.has(key))
             throw new Error(usage);
-        const entry = { command: process.execPath, args: [fileURLToPath(new URL("dist/index.js", root))] };
-        if (args[1] === "toml") {
-            console.log(`[mcp_servers.higgsfield-use-blender]\ncommand = ${JSON.stringify(entry.command)}\nargs = ${JSON.stringify(entry.args)}`);
-        }
+        seen.add(key);
+        if (key === "--blender")
+            executable = value;
+        else if (key === "--format" && command === "config" && ["json", "toml"].includes(value))
+            format = value;
+        else
+            throw new Error(usage);
+    }
+    executable = await resolveExecutable(executable);
+    if (command === "config") {
+        const entry = { command: process.execPath, args: [fileURLToPath(new URL("./index.js", import.meta.url))], env: { BLENDER_EXECUTABLE: executable } };
+        if (format === "toml")
+            console.log(`[mcp_servers.higgsfield-use-blender]\ncommand = ${JSON.stringify(entry.command)}\nargs = ${JSON.stringify(entry.args)}\n[mcp_servers.higgsfield-use-blender.env]\nBLENDER_EXECUTABLE = ${JSON.stringify(executable)}`);
         else
             console.log(JSON.stringify({ mcpServers: { "higgsfield-use-blender": entry } }, null, 2));
         return;
     }
-    if (command === "doctor") {
-        const connections = await discover();
-        console.log(JSON.stringify({ node: process.version, bridges: connections.map(({ pid, port }) => ({ pid, port })) }));
-        const job = await new BlenderTransport().execute("import bpy\nresult = {'version': bpy.app.version_string, 'file': bpy.data.filepath, 'scene': bpy.context.scene.name}", 5);
+    const transport = new BlenderTransport({ executable });
+    try {
+        const job = await transport.execute("import bpy, os\nresult = {'version': bpy.app.version_string, 'background': bpy.app.background, 'pid': os.getpid(), 'file': bpy.data.filepath}", 15);
         if (!job.ok)
             throw new Error(job.error || "Blender execution failed");
-        console.log(JSON.stringify(job.result));
-        return;
+        console.log(JSON.stringify({ executable, ...job }));
     }
-    if (command === "install-addon" || command === "launch") {
-        if (args[0] !== "--blender" || args.length !== 2)
-            throw new Error("Pass --blender with the absolute Blender executable path.");
-        const executable = args[1];
-        if (!isAbsolute(executable) || !(await stat(executable)).isFile())
-            throw new Error("--blender must point to an absolute executable file, not the .app directory.");
-        const script = fileURLToPath(new URL(command === "launch" ? "scripts/launch.py" : "scripts/install_addon.py", root));
-        const launchArgs = command === "launch" ? ["--python", script] : ["--background", "--factory-startup", "--python-exit-code", "1", "--python", script];
-        const child = spawn(executable, launchArgs, { stdio: command === "launch" ? "ignore" : "inherit", detached: command === "launch" });
-        await new Promise((resolve, reject) => {
-            child.once("error", reject);
-            if (command === "launch")
-                child.once("spawn", () => { child.unref(); resolve(); });
-            else
-                child.once("exit", code => code === 0 ? resolve() : reject(new Error(`Blender installer exited ${code}`)));
-        });
-        if (command === "launch")
-            console.log("Blender launched with the bridge bootstrap. Run doctor after startup to verify the connection.");
-        return;
+    finally {
+        await transport.close();
     }
-    throw new Error(usage);
 }
 main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/dist/index.js

@@ -1,4 +1,11 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { createServer } from "./server.js";
-await createServer().connect(new StdioServerTransport());
+import { BlenderTransport } from "./transport.js";
+const blender = new BlenderTransport();
+const server = createServer(blender);
+server.server.onclose = () => { void blender.close(); };
+const shutdown = async () => { await blender.close(); await server.close(); };
+process.once("SIGINT", () => { void shutdown(); });
+process.once("SIGTERM", () => { void shutdown(); });
+await server.connect(new StdioServerTransport());

package/dist/schemas.d.ts

@@ -62,6 +62,7 @@ export declare const setFrameShape: {
 };
 export declare const renderShape: {
     output_path: z.ZodString;
+    overwrite: z.ZodDefault<z.ZodBoolean>;
     resolution: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
     engine: z.ZodOptional<z.ZodEnum<{
         BLENDER_EEVEE_NEXT: "BLENDER_EEVEE_NEXT";
@@ -70,15 +71,6 @@ export declare const renderShape: {
     }>>;
     samples: z.ZodOptional<z.ZodNumber>;
 };
-export declare const screenshotShape: {
-    max_size: z.ZodOptional<z.ZodNumber>;
-    shading: z.ZodOptional<z.ZodEnum<{
-        SOLID: "SOLID";
-        MATERIAL: "MATERIAL";
-        RENDERED: "RENDERED";
-        WIREFRAME: "WIREFRAME";
-    }>>;
-};
 export declare const getObjectShape: {
     name: z.ZodString;
 };

package/dist/schemas.js

@@ -3,7 +3,7 @@ const vec3 = z.tuple([z.number(), z.number(), z.number()]);
 export const executeShape = {
     code: z
         .string().min(1).max(1_000_000)
-        .describe("Python source executed inside the connected Blender with full `bpy` "
+        .describe("Python source executed inside this MCP session’s background Blender with full `bpy` "
         + "access. To return data, assign a JSON-serialisable value to a variable "
         + "named `result`."),
 };
@@ -57,7 +57,8 @@ export const setFrameShape = {
     frame: z.number().int().describe("Frame number to set as current."),
 };
 export const renderShape = {
-    output_path: z.string().min(1).describe("Absolute path for the PNG. Default a temp file."),
+    output_path: z.string().min(1).describe("Absolute path for the PNG output."),
+    overwrite: z.boolean().default(false).describe("Allow replacing an existing output file."),
     resolution: z
         .tuple([z.number().int().min(1).max(16384), z.number().int().min(1).max(16384)])
         .optional()
@@ -66,18 +67,6 @@ export const renderShape = {
         .describe("Render engine. Default the scene's current engine."),
     samples: z.number().int().min(1).max(65536).optional().describe("Cycles sample count; requires the CYCLES engine."),
 };
-export const screenshotShape = {
-    max_size: z
-        .number()
-        .int()
-        .min(64).max(2048)
-        .optional()
-        .describe("Longest-edge pixel cap for the capture (keeps it under the 1MB message limit). Default 1280."),
-    shading: z
-        .enum(["SOLID", "MATERIAL", "RENDERED", "WIREFRAME"])
-        .optional()
-        .describe("Viewport shading to capture with. Default keeps the current viewport shading."),
-};
 export const getObjectShape = {
     name: z.string().describe("Exact object name to inspect."),
 };

package/dist/server.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { BL_TOOLS } from "./tools.js";
 import { BlenderTransport } from "./transport.js";
-import { getSkill, SKILL_NAMES } from "./skills.js";
+import { getSkill, getSkillAsset, listSkills } from "./skills.js";
 const packageInfo = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
 const errorResult = (error) => ({ isError: true, content: [{ type: "text", text: String(error) }] });
 export async function formatResult(job) {
@@ -32,7 +32,7 @@ export async function formatResult(job) {
 }
 export function createServer(transport = new BlenderTransport()) {
     const server = new McpServer({ name: "higgsfield-use-blender", title: "Higgsfield use Blender", version: packageInfo.version }, {
-        instructions: "Local Blender control. Read bl_get_skill(blender-scene), then bl_health and bl_get_scene_summary before edits. Prefer typed tools; use bl_execute for other bpy operations. Commands can partially mutate before errors. On timeout, query bl_job_status; never blindly retry. Render and view results. Cloud generation is provided by a separate Higgsfield MCP, not this server.",
+        instructions: "Control a dedicated background Blender process; it cannot access an open desktop window. Save .blend files before disconnecting; unsaved state is lost on reconnect. Read bl_get_skill(blender-scene), then bl_health and bl_get_scene_summary before edits. For specialized work, call bl_list_skills, load the relevant skill with bl_get_skill and only needed references; bl_get_skill_asset locates bundled assets. Prefer typed tools; use bl_execute for other bpy operations. Commands can partially mutate before errors. On timeout, query bl_job_status; never blindly retry. Render and view results. Cloud generation is provided by a separate Higgsfield MCP, not this server.",
     });
     for (const tool of BL_TOOLS) {
         server.registerTool(tool.name, {
@@ -40,7 +40,8 @@ export function createServer(transport = new BlenderTransport()) {
             annotations: { readOnlyHint: tool.readOnly, destructiveHint: !tool.readOnly, idempotentHint: tool.readOnly, openWorldHint: tool.name === "bl_execute" },
         }, async (args) => {
             try {
-                return await formatResult(await transport.execute(tool.code(args), tool.name === "bl_render" ? 300 : 120));
+                const mutates = !tool.readOnly && !["bl_save_project", "bl_open_project"].includes(tool.name);
+                return await formatResult(await transport.execute(tool.code(args), tool.name === "bl_render" ? 300 : 120, mutates));
             }
             catch (error) {
                 return errorResult(error);
@@ -48,7 +49,7 @@ export function createServer(transport = new BlenderTransport()) {
         });
     }
     server.registerTool("bl_job_status", {
-        title: "Check Blender Job", description: "Check a previously accepted job after timeout without repeating its mutations. Select the original Blender PID when multiple instances are open. Completed results expire after 128 newer accepted jobs or Blender exits.",
+        title: "Check Blender Job", description: "Check a previously accepted job after timeout without repeating its mutations. Use the same MCP session. Results expire after 128 accepted jobs or reconnecting.",
         inputSchema: z.object({ job_id: z.string().regex(/^[a-f0-9]{32}$/) }).strict(),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ job_id }) => {
@@ -59,10 +60,43 @@ export function createServer(transport = new BlenderTransport()) {
             return errorResult(error);
         }
     });
+    server.registerTool("bl_list_skills", {
+        title: "List Blender Skills", description: "List bundled Blender skill names, descriptions, references and assets. Does not require Blender to be running.",
+        inputSchema: z.object({}).strict(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            const index = await listSkills();
+            return { content: [{ type: "text", text: JSON.stringify(index) }], structuredContent: index };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
     server.registerTool("bl_get_skill", {
-        title: "Read Blender Skill", description: "Load offline Blender craft guidance. Start with blender-scene, then read the relevant topic. Does not require Blender to be running.",
-        inputSchema: z.object({ name: z.enum(SKILL_NAMES).default("blender-scene") }).strict(),
+        title: "Read Blender Skill", description: "Load a bundled Blender skill or one of its listed references. Start with blender-scene. Legacy topic names remain supported. Does not require Blender to be running.",
+        inputSchema: z.object({ name: z.string().default("blender-scene"), document: z.string().default("SKILL.md") }).strict(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ name, document }) => {
+        try {
+            return { content: [{ type: "text", text: await getSkill(name, document) }] };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("bl_get_skill_asset", {
+        title: "Locate Blender Skill Asset", description: "Return the absolute path and size of an asset bundled with a listed Blender skill. The path is local to the MCP host.",
+        inputSchema: z.object({ name: z.string(), path: z.string() }).strict(),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async ({ name }) => ({ content: [{ type: "text", text: await getSkill(name) }] }));
+    }, async ({ name, path }) => {
+        try {
+            const asset = await getSkillAsset(name, path);
+            return { content: [{ type: "text", text: JSON.stringify(asset) }], structuredContent: asset };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
     return server;
 }

package/dist/skills.d.ts

@@ -1,2 +1,15 @@
-export declare const SKILL_NAMES: readonly ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
-export declare function getSkill(name: typeof SKILL_NAMES[number]): Promise<string>;
+export declare function listSkills(): Promise<{
+    skills: {
+        name: string;
+        description: string;
+        references: string[];
+        assets: string[];
+    }[];
+}>;
+export declare function getSkill(name: string, document?: string): Promise<string>;
+export declare function getSkillAsset(name: string, path: string): Promise<{
+    name: string;
+    path: string;
+    absolute_path: string;
+    bytes: number;
+}>;

package/dist/skills.js

@@ -1,6 +1,90 @@
-import { readFile } from "node:fs/promises";
-export const SKILL_NAMES = ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
-export async function getSkill(name) {
-    const relative = name === "blender-scene" ? "SKILL.md" : `references/${name}.md`;
-    return readFile(new URL(`../skills/blender-scene/${relative}`, import.meta.url), "utf8");
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const root = fileURLToPath(new URL("../skills/", import.meta.url));
+const legacyReferences = new Set(["modeling", "materials", "lighting-camera", "animation"]);
+const skillName = /^blender-[a-z0-9-]+$/;
+const documentPath = /^references\/[a-zA-Z0-9/_-]+\.md$/;
+const assetPath = /^assets\/[a-zA-Z0-9][a-zA-Z0-9/._-]*$/;
+function validParts(path) {
+    return !path.split("/").some(part => part === "" || part === "." || part === "..");
+}
+async function bundledFile(name, path) {
+    const corpus = await realpath(root);
+    const base = await realpath(resolve(root, name));
+    const skillLocal = relative(corpus, base);
+    if (skillLocal === ".." || skillLocal.startsWith("../") || skillLocal.startsWith("..\\") || isAbsolute(skillLocal)) {
+        throw new Error("Skill path escapes the bundled corpus");
+    }
+    const file = await realpath(resolve(base, path));
+    const local = relative(base, file);
+    if (local === ".." || local.startsWith("../") || local.startsWith("..\\") || isAbsolute(local)) {
+        throw new Error("Skill path escapes the bundled corpus");
+    }
+    if (!(await stat(file)).isFile())
+        throw new Error("Skill path is not a file");
+    return file;
+}
+async function files(name, folder) {
+    try {
+        const candidates = (await readdir(resolve(root, name, folder), { recursive: true }))
+            .map(path => `${folder}/${path}`)
+            .filter(path => validParts(path) && (folder === "assets" ? assetPath.test(path) : documentPath.test(path)))
+            .sort();
+        const checked = await Promise.all(candidates.map(async (path) => {
+            if (!(await stat(resolve(root, name, path))).isFile())
+                return null;
+            await bundledFile(name, path);
+            return path;
+        }));
+        return checked.filter((path) => path !== null);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function requireSkill(name) {
+    if (!skillName.test(name))
+        throw new RangeError(`Unknown Blender skill '${name}'`);
+    try {
+        await bundledFile(name, "SKILL.md");
+    }
+    catch {
+        throw new RangeError(`Unknown Blender skill '${name}'. Call bl_list_skills for available names.`);
+    }
+}
+export async function listSkills() {
+    const entries = await readdir(root, { withFileTypes: true });
+    const names = entries.filter(entry => entry.isDirectory() && skillName.test(entry.name)).map(entry => entry.name).sort();
+    return { skills: await Promise.all(names.map(async (name) => {
+            const entry = await readFile(await bundledFile(name, "SKILL.md"), "utf8");
+            return {
+                name,
+                description: /^description:\s*(.+)$/m.exec(entry)?.[1] ?? "",
+                references: await files(name, "references"),
+                assets: await files(name, "assets"),
+            };
+        })) };
+}
+export async function getSkill(name, document = "SKILL.md") {
+    if (legacyReferences.has(name)) {
+        if (document !== "SKILL.md")
+            throw new RangeError("Legacy topic aliases do not have references");
+        return readFile(await bundledFile("blender-scene", `references/${name}.md`), "utf8");
+    }
+    await requireSkill(name);
+    if (document !== "SKILL.md" && (!validParts(document) || !documentPath.test(document) || !(await files(name, "references")).includes(document))) {
+        throw new RangeError(`Unknown reference '${document}' for '${name}'`);
+    }
+    return readFile(await bundledFile(name, document), "utf8");
+}
+export async function getSkillAsset(name, path) {
+    await requireSkill(name);
+    if (!validParts(path) || !assetPath.test(path) || !(await files(name, "assets")).includes(path)) {
+        throw new RangeError(`Unknown asset '${path}' for '${name}'`);
+    }
+    const absolute_path = await bundledFile(name, path);
+    return { name, path, absolute_path, bytes: (await stat(absolute_path)).size };
 }