fnf-blender-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Higgsfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# 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.
+
+```text
+Desktop MCP client ── stdio ── Node MCP server
+                                  │
+                     authenticated HTTP on 127.0.0.1
+                                  │
+                        Blender Python add-on
+                                  │
+                       main-thread timer → 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.
+
+## Quick start
+
+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):
+
+```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
+```
+
+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:
+
+```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.
+
+## Tools
+
+| Area | Tools |
+| --- | --- |
+| Inspect | `bl_health`, `bl_get_scene_summary`, `bl_get_object` |
+| Scene | `bl_add_primitive`, `bl_delete_object`, `bl_set_transform`, `bl_set_material`, `bl_import_model` |
+| 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` |
+| 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.
+
+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`.
+
+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.
+
+## Connection and timeout behavior
+
+- 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.
+
+## Development and verification
+
+From a source checkout, run `npm ci` first. Development checks:
+
+```sh
+npm test
+npm run typecheck
+npm run test:package
+```
+
+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
+
+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 [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for the MIT license.

package/UPSTREAM.md

@@ -0,0 +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.

package/addon/higgsfield_use_blender/__init__.py

@@ -0,0 +1,39 @@
+bl_info = {
+    "name": "Higgsfield use Blender",
+    "author": "Higgsfield",
+    "version": (0, 1, 0),
+    "blender": (4, 2, 0),
+    "category": "Interface",
+    "description": "Local MCP control over authenticated loopback HTTP",
+}
+
+import bpy
+import atexit
+from .bridge import Bridge
+
+_bridge = None
+
+
+def _pump():
+    return _bridge.pump() if _bridge else None
+
+
+def register():
+    global _bridge
+    if _bridge:
+        return
+    bridge = Bridge(namespace=lambda: {"bpy": bpy})
+    bridge.start()
+    _bridge = bridge
+    atexit.register(bridge.stop)
+    bpy.app.timers.register(_pump, first_interval=0.05, persistent=True)
+
+
+def unregister():
+    global _bridge
+    if bpy.app.timers.is_registered(_pump):
+        bpy.app.timers.unregister(_pump)
+    if _bridge:
+        atexit.unregister(_bridge.stop)
+        _bridge.stop()
+        _bridge = None

package/addon/higgsfield_use_blender/bridge.py

@@ -0,0 +1,197 @@
+"""Authenticated loopback transport; Blender data is accessed only by pump()."""
+
+import contextlib
+import hmac
+import io
+import json
+import os
+from pathlib import Path
+import queue
+import secrets
+import threading
+import time
+import traceback
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+PROTOCOL = "higgsfield-blender/1"
+MAX_BODY = 1_100_000
+MAX_RESULT = 4 * 1024 * 1024
+
+
+class CappedOutput(io.StringIO):
+    def write(self, text):
+        remaining = max(0, 65536 - self.tell())
+        super().write(text[:remaining])
+        return len(text)
+
+
+class Job:
+    def __init__(self, code, timeout):
+        self.id = secrets.token_hex(16)
+        self.code = code
+        self.deadline = time.monotonic() + timeout
+        self.state = "queued"
+        self.response = None
+        self.completed = threading.Event()
+
+
+class Bridge:
+    def __init__(self, runtime_dir=None, namespace=None):
+        self.directory = Path(runtime_dir or os.environ.get("BLENDER_MCP_RUNTIME_DIR", "") or Path.home() / ".higgsfield" / "blender")
+        self.namespace = namespace or (lambda: {})
+        self.token = secrets.token_hex(32)
+        self.jobs = {}
+        self.pending = queue.Queue(maxsize=32)
+        self.lock = threading.Lock()
+        self.server = None
+        self.discovery = self.directory / ("bridge-%s.json" % os.getpid())
+
+    def start(self):
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        bridge = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *_args):
+                pass
+
+            def setup(self):
+                super().setup()
+                self.connection.settimeout(10)
+
+            def send_json(self, status, value):
+                data = json.dumps(value, allow_nan=False).encode("utf-8")
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                self.send_header("Cache-Control", "no-store")
+                self.end_headers()
+                try:
+                    self.wfile.write(data)
+                except (BrokenPipeError, ConnectionResetError):
+                    pass
+
+            def authorized(self):
+                expected_host = "127.0.0.1:%s" % self.server.server_port
+                if self.headers.get("Origin") is not None or self.headers.get("Host") != expected_host:
+                    self.send_json(403, {"error": "Local clients only"})
+                    return False
+                expected = "Bearer " + bridge.token
+                if not hmac.compare_digest(self.headers.get("Authorization", "").encode(), expected.encode()):
+                    self.send_json(401, {"error": "Invalid bridge token"})
+                    return False
+                return True
+
+            def do_GET(self):
+                if not self.authorized():
+                    return
+                if self.path == "/health":
+                    self.send_json(200, {"protocol": PROTOCOL, "pid": os.getpid()})
+                    return
+                if self.path.startswith("/jobs/"):
+                    with bridge.lock:
+                        job = bridge.jobs.get(self.path[len("/jobs/"):])
+                        value = bridge.snapshot(job) if job else None
+                    self.send_json(200 if value else 404, value or {"error": "Unknown or expired job"})
+                    return
+                self.send_json(404, {"error": "Unknown endpoint"})
+
+            def do_POST(self):
+                if not self.authorized():
+                    return
+                if self.path != "/execute":
+                    self.send_json(404, {"error": "Unknown endpoint"})
+                    return
+                if self.headers.get("Content-Type", "").split(";")[0] != "application/json":
+                    self.send_json(415, {"error": "Expected application/json"})
+                    return
+                try:
+                    length = int(self.headers.get("Content-Length", "0"))
+                    if not 0 < length <= MAX_BODY:
+                        raise ValueError("Request body must be 1..1100000 bytes")
+                    body = json.loads(self.rfile.read(length))
+                    code = body.get("code")
+                    timeout = body.get("timeout_seconds", 120)
+                    if not isinstance(code, str) or not code or len(code) > 1_000_000:
+                        raise ValueError("code must be a non-empty string up to 1000000 characters")
+                    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 1 <= timeout <= 600:
+                        raise ValueError("timeout_seconds must be 1..600")
+                except (ValueError, AttributeError, UnicodeError) as exc:
+                    self.send_json(400, {"error": str(exc)})
+                    return
+                with bridge.lock:
+                    if len(bridge.jobs) >= 128:
+                        for job_id, old in list(bridge.jobs.items()):
+                            if old.completed.is_set():
+                                del bridge.jobs[job_id]
+                                break
+                    job = Job(code, timeout)
+                    try:
+                        bridge.pending.put_nowait(job)
+                    except queue.Full:
+                        self.send_json(503, {"error": "Execution queue is full; request was not accepted"})
+                        return
+                    bridge.jobs[job.id] = job
+                self.send_json(202, {"job_id": job.id, "state": "queued"})
+
+        class Server(ThreadingHTTPServer):
+            daemon_threads = True
+
+        self.server = Server(("127.0.0.1", 0), Handler)
+        record = {"protocol": PROTOCOL, "pid": os.getpid(), "port": self.server.server_port, "token": self.token}
+        try:
+            fd = os.open(self.discovery, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(fd, "w") as handle:
+                json.dump(record, handle)
+        except Exception:
+            self.server.server_close()
+            self.server = None
+            raise
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+
+    @staticmethod
+    def snapshot(job):
+        return {"job_id": job.id, "state": job.state, **(job.response or {})}
+
+    def pump(self):
+        try:
+            job = self.pending.get_nowait()
+        except queue.Empty:
+            return 0.05
+        with self.lock:
+            if time.monotonic() > job.deadline:
+                job.state = "expired"
+                job.response = {"ok": False, "error": "Expired before execution; no code ran"}
+                job.completed.set()
+                return 0.05
+            job.state = "running"
+        stdout, stderr = CappedOutput(), CappedOutput()
+        try:
+            namespace = {"__name__": "__blender_mcp__", **self.namespace()}
+            with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+                exec(compile(job.code, "<blender-mcp>", "exec"), namespace)
+            response = {"ok": True, "result": namespace.get("result"), "stdout": stdout.getvalue(), "stderr": stderr.getvalue()}
+            encoded = json.dumps(response, allow_nan=False)
+            if len(encoded.encode("utf-8")) > MAX_RESULT:
+                raise ValueError("Result exceeds 4 MiB; return a file path or smaller result")
+        except BaseException:
+            response = {"ok": False, "error": traceback.format_exc(), "stdout": stdout.getvalue(), "stderr": stderr.getvalue()}
+        with self.lock:
+            job.response = response
+            job.state = "completed"
+            job.code = ""
+            job.completed.set()
+        return 0.05
+
+    def stop(self):
+        if self.server:
+            self.server.shutdown()
+            self.server.server_close()
+            self.thread.join(timeout=2)
+            self.server = None
+            try:
+                record = json.loads(self.discovery.read_text())
+                if record.get("token") == self.token:
+                    self.discovery.unlink()
+            except (FileNotFoundError, ValueError):
+                pass

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/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);
+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
+
+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.`;
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    if (["help", "--help", "-h"].includes(command)) {
+        console.log(usage);
+        return;
+    }
+    if (command === "serve") {
+        await import("./index.js");
+        return;
+    }
+    if (command === "config") {
+        if (args.length && (args[0] !== "--format" || args.length !== 2 || !["json", "toml"].includes(args[1])))
+            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)}`);
+        }
+        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);
+        if (!job.ok)
+            throw new Error(job.error || "Blender execution failed");
+        console.log(JSON.stringify(job.result));
+        return;
+    }
+    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;
+    }
+    throw new Error(usage);
+}
+main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { createServer } from "./server.js";
+await createServer().connect(new StdioServerTransport());

package/dist/schemas.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+export declare const executeShape: {
+    code: z.ZodString;
+};
+export declare const sceneSummaryShape: {};
+export declare const addPrimitiveShape: {
+    kind: z.ZodEnum<{
+        cube: "cube";
+        uv_sphere: "uv_sphere";
+        ico_sphere: "ico_sphere";
+        cylinder: "cylinder";
+        cone: "cone";
+        plane: "plane";
+        torus: "torus";
+        monkey: "monkey";
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+};
+export declare const deleteObjectShape: {
+    name: z.ZodString;
+};
+export declare const setTransformShape: {
+    name: z.ZodString;
+    location: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    rotation_euler: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    scale: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+};
+export declare const setMaterialShape: {
+    object: z.ZodString;
+    color: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    metallic: z.ZodOptional<z.ZodNumber>;
+    roughness: z.ZodOptional<z.ZodNumber>;
+    material_name: z.ZodOptional<z.ZodString>;
+};
+export declare const importModelShape: {
+    path: z.ZodString;
+    location: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+};
+export declare const addLightShape: {
+    type: z.ZodEnum<{
+        POINT: "POINT";
+        SUN: "SUN";
+        SPOT: "SPOT";
+        AREA: "AREA";
+    }>;
+    location: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    energy: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+};
+export declare const addCameraShape: {
+    location: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    rotation_euler: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    set_active: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodOptional<z.ZodString>;
+};
+export declare const setActiveCameraShape: {
+    name: z.ZodString;
+};
+export declare const setFrameShape: {
+    frame: z.ZodNumber;
+};
+export declare const renderShape: {
+    output_path: z.ZodString;
+    resolution: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    engine: z.ZodOptional<z.ZodEnum<{
+        BLENDER_EEVEE_NEXT: "BLENDER_EEVEE_NEXT";
+        CYCLES: "CYCLES";
+        BLENDER_WORKBENCH: "BLENDER_WORKBENCH";
+    }>>;
+    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

@@ -0,0 +1,83 @@
+import { z } from "zod";
+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` "
+        + "access. To return data, assign a JSON-serialisable value to a variable "
+        + "named `result`."),
+};
+export const sceneSummaryShape = {};
+export const addPrimitiveShape = {
+    kind: z
+        .enum(["cube", "uv_sphere", "ico_sphere", "cylinder", "cone", "plane", "torus", "monkey"])
+        .describe("Primitive type to add."),
+    name: z.string().optional().describe("Rename the created object to this."),
+    location: vec3.optional().describe("World position [x, y, z] in metres (Z up). Default [0,0,0]."),
+};
+export const deleteObjectShape = {
+    name: z.string().describe("Exact name of the object to delete."),
+};
+export const setTransformShape = {
+    name: z.string().describe("Exact object name to transform."),
+    location: vec3.optional().describe("Parent-relative location [x, y, z] in scene units."),
+    rotation_euler: vec3.optional().describe("Euler rotation [x, y, z] in RADIANS (XYZ)."),
+    scale: vec3.optional().describe("Scale factors [x, y, z] (1 = unchanged)."),
+};
+export const setMaterialShape = {
+    object: z.string().describe("Exact object name to receive the material."),
+    color: z
+        .tuple([z.number(), z.number(), z.number(), z.number()])
+        .optional()
+        .describe("Base colour RGBA, each 0-1. Default opaque mid-grey."),
+    metallic: z.number().min(0).max(1).optional().describe("Metallic 0-1."),
+    roughness: z.number().min(0).max(1).optional().describe("Roughness 0-1."),
+    material_name: z.string().optional().describe("Name for the created material."),
+};
+export const importModelShape = {
+    path: z.string().min(1).describe("Absolute local file path to import instead of a URL."),
+    location: vec3.optional().describe("Move the imported root to this world position."),
+};
+export const addLightShape = {
+    type: z.enum(["POINT", "SUN", "SPOT", "AREA"]).describe("Light type."),
+    location: vec3.optional().describe("World position [x, y, z]. Default [0,0,5]."),
+    energy: z.number().optional().describe("Light power/energy (watts). Default 1000 for POINT/SPOT/AREA, 5 for SUN."),
+    name: z.string().optional().describe("Rename the created light."),
+};
+export const addCameraShape = {
+    location: vec3.optional().describe("World position [x, y, z]. Default [7.36, -6.93, 4.96]."),
+    rotation_euler: vec3.optional().describe("Euler rotation [x, y, z] in RADIANS. Default a 3/4 view."),
+    set_active: z.boolean().optional().describe("Make this the active scene camera. Default true."),
+    name: z.string().optional().describe("Rename the created camera."),
+};
+export const setActiveCameraShape = {
+    name: z.string().describe("Exact camera object name to make active."),
+};
+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."),
+    resolution: z
+        .tuple([z.number().int().min(1).max(16384), z.number().int().min(1).max(16384)])
+        .optional()
+        .describe("Render [width, height] in pixels. Default the scene's current setting."),
+    engine: z.enum(["BLENDER_EEVEE_NEXT", "CYCLES", "BLENDER_WORKBENCH"]).optional()
+        .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.d.ts

@@ -0,0 +1,4 @@
+import { McpServer, type CallToolResult } from "@modelcontextprotocol/server";
+import { BlenderTransport, type JobResult } from "./transport.js";
+export declare function formatResult(job: JobResult): Promise<CallToolResult>;
+export declare function createServer(transport?: BlenderTransport): McpServer;