fnf-blender-mcp 0.1.0 → 0.2.0

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. Verify that 0.2.0 is published before installing it; this source change alone does not publish a release.
 
 ```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@0.2.0 version --registry=https://registry.npmjs.org/
+blenderDir="$HOME/.higgsfield/blender-mcp"
+npm install --prefix "$blenderDir" --registry=https://registry.npmjs.org/ fnf-blender-mcp@0.2.0
+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,35 @@ 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` |
 
-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`.
+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.
 
-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.
+## Session lifecycle
 
-## Connection and timeout behavior
+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.
 
-- 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.
+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.
 
-## Development and verification
+## Development and validation
 
-From a source checkout, run `npm ci` first. Development checks:
+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.
-
-## Slash command
+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 19 tools, offline guidance and the absence of add-on files. `test:live` uses real Blender for geometry, materials, keyframes, file guards and a small Cycles render in disposable files.
 
-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.
+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.
 
-See [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for the MIT license.
+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.

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.0 is prepared for the transition to a background process. 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 the version in README.md and skills/use-blender aligned with the fnf-mcp-server command bundle. Review migration instructions for removed commands and tools.
+4. Run `npm pack --json`, review the contents, then publish the reviewed archive with `npm publish ./fnf-blender-mcp-0.2.0.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

@@ -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. 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, {
@@ -48,7 +48,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 }) => {

package/dist/tools.js

@@ -9,7 +9,7 @@ function scriptTool(name, title, description, shape, body) {
     };
 }
 export const BL_TOOLS = [
-    scriptTool("bl_execute", "Execute Python (bpy)", "Run arbitrary Python inside the connected Blender with full `bpy` access. "
+    scriptTool("bl_execute", "Execute Python (bpy)", "Run arbitrary Python inside this MCP session’s background Blender with full `bpy` access. "
         + "Assign a JSON-serialisable value to `result` to return data. This is the "
         + "escape hatch — prefer a specific bl_* tool when one exists.", schemas.executeShape, ""),
     scriptTool("bl_get_scene_summary", "Get Scene Summary", "Return a compact summary of the active scene: name, current frame, render "
@@ -164,59 +164,6 @@ finally:
      _scene.render.resolution_percentage, _scene.render.filepath, _scene.render.image_settings.file_format) = _old
     if _old_samples is not None:
         _scene.cycles.samples = _old_samples`),
-    scriptTool("bl_screenshot", "Screenshot Viewport", "Capture what the 3D viewport currently shows (the agent's eyes) as an "
-        + "OpenGL viewport render, and return an inline PNG. Use this to SEE the scene "
-        + "before and after edits instead of guessing.", schemas.screenshotShape, `import base64, os, tempfile
-_scene = bpy.context.scene
-_orig_res = (_scene.render.resolution_x, _scene.render.resolution_y, _scene.render.resolution_percentage)
-_orig_fp = _scene.render.filepath
-_orig_fmt = _scene.render.image_settings.file_format
-_cap = int(_args.get("max_size") or 1280)
-_w, _h = _scene.render.resolution_x, _scene.render.resolution_y
-_longest = max(_w, _h) or _cap
-_scale = min(1.0, _cap / _longest)
-_area = None
-_win = None
-for _wnd in bpy.context.window_manager.windows:
-    for _a in _wnd.screen.areas:
-        if _a.type == "VIEW_3D":
-            _area, _win = _a, _wnd
-            break
-    if _area:
-        break
-_shading_prev = None
-if _args.get("shading") and _area is not None:
-    _sp = _area.spaces.active
-    _shading_prev = _sp.shading.type
-    _sp.shading.type = _args["shading"]
-_fd, _path = tempfile.mkstemp(suffix=".png", prefix="hf_shot_")
-os.close(_fd)
-try:
-    _scene.render.resolution_x = max(1, int(_w * _scale))
-    _scene.render.resolution_y = max(1, int(_h * _scale))
-    _scene.render.resolution_percentage = 100
-    _scene.render.filepath = _path
-    _scene.render.image_settings.file_format = "PNG"
-    if _area is not None:
-        _region = next((_r for _r in _area.regions if _r.type == "WINDOW"), None)
-        with bpy.context.temp_override(window=_win, area=_area, region=_region):
-            bpy.ops.render.opengl(write_still=True)
-    else:
-        raise RuntimeError("No VIEW_3D area is available; use bl_render with a scene camera")
-    with open(_path, "rb") as _fh:
-        _raw = _fh.read()
-    result = {"pngBase64": base64.b64encode(_raw).decode("ascii"),
-              "width": _scene.render.resolution_x, "height": _scene.render.resolution_y}
-finally:
-    _scene.render.resolution_x, _scene.render.resolution_y, _scene.render.resolution_percentage = _orig_res
-    _scene.render.filepath = _orig_fp
-    _scene.render.image_settings.file_format = _orig_fmt
-    if _shading_prev is not None and _area is not None:
-        _area.spaces.active.shading.type = _shading_prev
-    try:
-        os.remove(_path)
-    except OSError:
-        pass`),
     scriptTool("bl_get_object", "Get Object Detail", "Detailed inspection of one object: transform, dimensions, bounding box, "
         + "material slots, modifiers, parent, and mesh stats (verts/edges/faces).", schemas.getObjectShape, `_o = bpy.data.objects.get(_args["name"])
 if _o is None:
@@ -240,7 +187,7 @@ if _o.type == "MESH" and _o.data is not None:
                      "polygons": len(_o.data.polygons)}
 result = _info`),
 ];
-BL_TOOLS.push(scriptTool("bl_health", "Inspect Blender", "Read the live Blender version, process, active file and scene; proves main-thread execution.", {}, `import os
+BL_TOOLS.push(scriptTool("bl_health", "Inspect Blender", "Start or inspect this MCP session’s background Blender. Returns its version, PID, active file and scene; does not inspect an open desktop window.", {}, `import os
 result = {"version": bpy.app.version_string, "pid": os.getpid(), "background": bpy.app.background,
           "file": bpy.data.filepath, "dirty": bpy.data.is_dirty, "scene": bpy.context.scene.name}`), scriptTool("bl_save_project", "Save Blender Project", "Save the current scene to an absolute .blend path. Existing files require overwrite=true.", {
     path: z.string().min(1), overwrite: z.boolean().default(false),
@@ -259,7 +206,7 @@ if not os.path.isabs(_path) or not os.path.isfile(_path) or not _path.lower().en
     raise ValueError("Provide an existing absolute .blend path")
 if bpy.data.is_dirty and not _args["discard_unsaved"]:
     raise ValueError("The current project has unsaved changes; save first or explicitly set discard_unsaved=true")
-bpy.ops.wm.open_mainfile(filepath=_path)
+bpy.ops.wm.open_mainfile(filepath=_path, use_scripts=False)
 result = {"path": bpy.data.filepath, "scene": bpy.context.scene.name}`), scriptTool("bl_insert_keyframe", "Insert Object Keyframe", "Key the current location, Euler rotation or scale of a named object at a frame.", {
     name: z.string().min(1), property: z.enum(["location", "rotation_euler", "scale"]), frame: z.number().int(),
 }, `_obj = bpy.data.objects.get(_args["name"])

package/dist/transport.d.ts

@@ -1,31 +1,30 @@
-import { z } from "zod";
-export declare const runtimeDirectory: () => string;
-declare const connectionSchema: z.ZodObject<{
-    protocol: z.ZodLiteral<"higgsfield-blender/1">;
-    pid: z.ZodNumber;
-    port: z.ZodNumber;
-    token: z.ZodString;
-}, z.core.$strip>;
-export type Connection = z.infer<typeof connectionSchema>;
-declare const jobSchema: z.ZodObject<{
-    job_id: z.ZodString;
-    state: z.ZodEnum<{
-        queued: "queued";
-        running: "running";
-        completed: "completed";
-        expired: "expired";
-    }>;
-    ok: z.ZodOptional<z.ZodBoolean>;
-    result: z.ZodOptional<z.ZodUnknown>;
-    error: z.ZodOptional<z.ZodString>;
-    stdout: z.ZodOptional<z.ZodString>;
-    stderr: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type JobResult = z.infer<typeof jobSchema>;
-export declare function discover(directory?: string): Promise<Connection[]>;
+export interface JobResult {
+    job_id: string;
+    state: "running" | "completed";
+    ok?: boolean;
+    result?: unknown;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function resolveExecutable(explicit?: string | undefined): Promise<string>;
 export declare class BlenderTransport {
-    connection(): Promise<Connection>;
-    status(jobId: string, connection?: Connection): Promise<JobResult>;
+    private options;
+    private child?;
+    private startup?;
+    private fault?;
+    private closed;
+    private killTimer?;
+    private active?;
+    private jobs;
+    constructor(options?: {
+        executable?: string;
+        startupTimeoutMs?: number;
+    });
+    private fail;
+    private start;
+    private launch;
+    status(jobId: string): Promise<JobResult>;
     execute(code: string, timeoutSeconds?: number): Promise<JobResult>;
+    close(): Promise<void>;
 }
-export {};