fnf-blender-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,68 @@
+import { readFile, stat } from "node:fs/promises";
+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";
+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) {
+    const data = job.result;
+    const object = data && typeof data === "object" && !Array.isArray(data) ? data : undefined;
+    const image = object?.pngBase64;
+    const { pngBase64: _removed, ...metadata } = object ?? {};
+    const structuredContent = { ...job, result: object ? metadata : data ?? null };
+    const content = [{ type: "text", text: JSON.stringify(structuredContent) }];
+    if (job.ok && typeof image === "string") {
+        content.push({ type: "image", data: image, mimeType: "image/png" });
+    }
+    if (job.ok && typeof object?.output_path === "string") {
+        const path = object.output_path;
+        try {
+            const file = await stat(path);
+            if (file.size <= 4 * 1024 * 1024 && path.toLowerCase().endsWith(".png")) {
+                content.push({ type: "image", data: (await readFile(path)).toString("base64"), mimeType: "image/png" });
+            }
+        }
+        catch {
+            content.push({ type: "text", text: "Preview unavailable; inspect the returned output path." });
+        }
+    }
+    return { content, structuredContent, ...(job.ok === false ? { isError: true } : {}) };
+}
+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.",
+    });
+    for (const tool of BL_TOOLS) {
+        server.registerTool(tool.name, {
+            title: tool.title, description: tool.description, inputSchema: tool.schema,
+            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));
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        });
+    }
+    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.",
+        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 }) => {
+        try {
+            return await formatResult(await transport.status(job_id));
+        }
+        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(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ name }) => ({ content: [{ type: "text", text: await getSkill(name) }] }));
+    return server;
+}

package/dist/skills.d.ts

@@ -0,0 +1,2 @@
+export declare const SKILL_NAMES: readonly ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
+export declare function getSkill(name: typeof SKILL_NAMES[number]): Promise<string>;

package/dist/skills.js

@@ -0,0 +1,6 @@
+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");
+}

package/dist/tools.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export interface BlenderTool {
+    name: string;
+    title: string;
+    description: string;
+    schema: z.ZodObject;
+    code: (args: Record<string, unknown>) => string;
+    readOnly: boolean;
+}
+export declare const BL_TOOLS: BlenderTool[];

package/dist/tools.js

@@ -0,0 +1,270 @@
+import { z } from "zod";
+import * as schemas from "./schemas.js";
+const readTools = new Set(["bl_get_scene_summary", "bl_get_object"]);
+function scriptTool(name, title, description, shape, body) {
+    return {
+        name, title, description, schema: z.object(shape).strict(), readOnly: readTools.has(name),
+        code: args => name === "bl_execute" ? String(args.code) :
+            `import bpy, json, base64\n_args = json.loads(base64.b64decode("${Buffer.from(JSON.stringify(args)).toString("base64")}"))\n${body}\n`,
+    };
+}
+export const BL_TOOLS = [
+    scriptTool("bl_execute", "Execute Python (bpy)", "Run arbitrary Python inside the connected 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 "
+        + "engine, and every object's name/type/location.", schemas.sceneSummaryShape, `scene = bpy.context.scene
+result = {
+    "scene": scene.name,
+    "frame_current": scene.frame_current,
+    "frame_range": [scene.frame_start, scene.frame_end],
+    "render_engine": scene.render.engine,
+    "objects": [
+        {"name": o.name, "type": o.type, "location": [round(c, 4) for c in o.location]}
+        for o in scene.objects
+    ],
+}`),
+    scriptTool("bl_add_primitive", "Add Primitive Mesh", "Add a primitive mesh (cube, sphere, cylinder, cone, plane, torus, monkey) "
+        + "to the active scene at an optional world location (metres, Z up).", schemas.addPrimitiveShape, `_op = {
+    "cube": bpy.ops.mesh.primitive_cube_add,
+    "uv_sphere": bpy.ops.mesh.primitive_uv_sphere_add,
+    "ico_sphere": bpy.ops.mesh.primitive_ico_sphere_add,
+    "cylinder": bpy.ops.mesh.primitive_cylinder_add,
+    "cone": bpy.ops.mesh.primitive_cone_add,
+    "plane": bpy.ops.mesh.primitive_plane_add,
+    "torus": bpy.ops.mesh.primitive_torus_add,
+    "monkey": bpy.ops.mesh.primitive_monkey_add,
+}[_args["kind"]]
+_loc = tuple(_args.get("location") or (0.0, 0.0, 0.0))
+_op(location=_loc)
+_obj = bpy.context.active_object
+if _args.get("name"):
+    _obj.name = _args["name"]
+result = {"created": _obj.name, "type": _obj.type, "location": list(_obj.location)}`),
+    scriptTool("bl_delete_object", "Delete Object", "Delete an object from the scene by exact name.", schemas.deleteObjectShape, `_obj = bpy.data.objects.get(_args["name"])
+if _obj is None:
+    raise ValueError("No object named %r" % _args["name"])
+bpy.data.objects.remove(_obj, do_unlink=True)
+result = {"deleted": _args["name"]}`),
+    scriptTool("bl_set_transform", "Set Transform", "Set any subset of an object's local location (scene units), rotation (radians, XYZ "
+        + "euler) and scale.", schemas.setTransformShape, `_obj = bpy.data.objects.get(_args["name"])
+if _obj is None:
+    raise ValueError("No object named %r" % _args["name"])
+if _args.get("location") is not None:
+    _obj.location = tuple(_args["location"])
+if _args.get("rotation_euler") is not None:
+    _obj.rotation_euler = tuple(_args["rotation_euler"])
+if _args.get("scale") is not None:
+    _obj.scale = tuple(_args["scale"])
+result = {
+    "name": _obj.name,
+    "location": list(_obj.location),
+    "rotation_euler": list(_obj.rotation_euler),
+    "scale": list(_obj.scale),
+}`),
+    scriptTool("bl_set_material", "Set Material", "Create and assign a Principled BSDF material (base colour RGBA 0-1, "
+        + "metallic, roughness) to an object.", schemas.setMaterialShape, `_obj = bpy.data.objects.get(_args["object"])
+if _obj is None:
+    raise ValueError("No object named %r" % _args["object"])
+if _obj.data is None or not hasattr(_obj.data, "materials"):
+    raise ValueError("This object type has no material slots")
+_mat = bpy.data.materials.new(name=_args.get("material_name") or (_obj.name + "_mat"))
+_mat.use_nodes = True
+_bsdf = _mat.node_tree.nodes.get("Principled BSDF")
+if _bsdf is not None:
+    if _args.get("color") is not None:
+        _bsdf.inputs["Base Color"].default_value = tuple(_args["color"])
+    if _args.get("metallic") is not None:
+        _bsdf.inputs["Metallic"].default_value = float(_args["metallic"])
+    if _args.get("roughness") is not None:
+        _bsdf.inputs["Roughness"].default_value = float(_args["roughness"])
+if _obj.data is not None and hasattr(_obj.data, "materials"):
+    if _obj.data.materials:
+        _obj.data.materials[0] = _mat
+    else:
+        _obj.data.materials.append(_mat)
+result = {"object": _obj.name, "material": _mat.name}`),
+    scriptTool("bl_import_model", "Import 3D Model", "Import an absolute local glb/gltf/fbx/obj file into the scene. Download external assets first with the client's file tools.", schemas.importModelShape, `import os
+_path = _args["path"]
+if not os.path.isabs(_path) or not os.path.isfile(_path):
+    raise ValueError("path must be an existing absolute file path")
+_ext = os.path.splitext(_path)[1].lower()
+_before = set(o.name for o in bpy.data.objects)
+if _ext in (".glb", ".gltf"):
+    bpy.ops.import_scene.gltf(filepath=_path)
+elif _ext == ".fbx":
+    bpy.ops.import_scene.fbx(filepath=_path)
+elif _ext == ".obj":
+    bpy.ops.wm.obj_import(filepath=_path)
+else:
+    raise ValueError("Unsupported model extension: %s" % _ext)
+_new = [o for o in bpy.data.objects if o.name not in _before]
+if _args.get("location") is not None and _new:
+    for _o in _new:
+        if _o.parent is None:
+            _o.location = tuple(_args["location"])
+result = {"imported": [o.name for o in _new], "path": _path}`),
+    scriptTool("bl_add_light", "Add Light", "Add a POINT/SUN/SPOT/AREA light at a world position with an energy.", schemas.addLightShape, `_type = _args["type"]
+_data = bpy.data.lights.new(name=_args.get("name") or (_type.title() + "Light"), type=_type)
+_energy = _args.get("energy")
+_data.energy = float(_energy) if _energy is not None else (5.0 if _type == "SUN" else 1000.0)
+_obj = bpy.data.objects.new(name=_data.name, object_data=_data)
+bpy.context.scene.collection.objects.link(_obj)
+_obj.location = tuple(_args.get("location") or (0.0, 0.0, 5.0))
+result = {"created": _obj.name, "type": _type, "energy": _data.energy}`),
+    scriptTool("bl_add_camera", "Add Camera", "Add a camera at a world position/rotation, optionally making it the "
+        + "active scene camera.", schemas.addCameraShape, `_data = bpy.data.cameras.new(name=_args.get("name") or "Camera")
+_obj = bpy.data.objects.new(name=_data.name, object_data=_data)
+bpy.context.scene.collection.objects.link(_obj)
+_obj.location = tuple(_args.get("location") or (7.3589, -6.9258, 4.9583))
+_obj.rotation_euler = tuple(_args.get("rotation_euler") or (1.1093, 0.0, 0.8149))
+if _args.get("set_active", True):
+    bpy.context.scene.camera = _obj
+result = {"created": _obj.name, "active": bpy.context.scene.camera == _obj}`),
+    scriptTool("bl_set_active_camera", "Set Active Camera", "Make an existing camera object the active scene camera.", schemas.setActiveCameraShape, `_obj = bpy.data.objects.get(_args["name"])
+if _obj is None or _obj.type != "CAMERA":
+    raise ValueError("No camera named %r" % _args["name"])
+bpy.context.scene.camera = _obj
+result = {"active_camera": _obj.name}`),
+    scriptTool("bl_set_frame", "Set Current Frame", "Set the scene's current frame.", schemas.setFrameShape, `bpy.context.scene.frame_set(int(_args["frame"]))
+result = {"frame_current": bpy.context.scene.frame_current}`),
+    scriptTool("bl_render", "Render Frame", "Render the current camera frame to PNG with optional temporary resolution, engine and sample overrides. Returns a local path and an inline preview when small enough.", schemas.renderShape, `import os, tempfile
+_scene = bpy.context.scene
+if _scene.camera is None:
+    raise ValueError("Set an active scene camera before rendering")
+_out = _args.get("output_path")
+if _out and (not os.path.isabs(_out) or not _out.lower().endswith(".png")):
+    raise ValueError("output_path must be an absolute .png path")
+if _out and os.path.exists(_out) and not _args.get("overwrite", False):
+    raise ValueError("Output exists; choose another path or set overwrite=true")
+if not _out:
+    _fd, _out = tempfile.mkstemp(suffix=".png", prefix="hf_render_")
+    os.close(_fd)
+_old = (_scene.render.engine, _scene.render.resolution_x, _scene.render.resolution_y,
+        _scene.render.resolution_percentage, _scene.render.filepath, _scene.render.image_settings.file_format)
+_old_samples = _scene.cycles.samples if hasattr(_scene, "cycles") else None
+try:
+    if _args.get("engine"):
+        _scene.render.engine = _args["engine"]
+    if _args.get("resolution") is not None:
+        _scene.render.resolution_x, _scene.render.resolution_y = _args["resolution"]
+        _scene.render.resolution_percentage = 100
+    if _args.get("samples") is not None:
+        if _scene.render.engine != "CYCLES":
+            raise ValueError("samples override currently supports CYCLES only")
+        _scene.cycles.samples = _args["samples"]
+    _scene.render.filepath = _out
+    _scene.render.image_settings.file_format = "PNG"
+    bpy.ops.render.render(write_still=True)
+    _image = bpy.data.images.get("Render Result")
+    result = {"output_path": _out, "engine": _scene.render.engine,
+              "resolution": list(_image.size) if _image else None}
+finally:
+    (_scene.render.engine, _scene.render.resolution_x, _scene.render.resolution_y,
+     _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:
+    raise ValueError("No object named %r" % _args["name"])
+_info = {
+    "name": _o.name,
+    "type": _o.type,
+    "location": [round(c, 4) for c in _o.location],
+    "rotation_euler": [round(c, 4) for c in _o.rotation_euler],
+    "scale": [round(c, 4) for c in _o.scale],
+    "dimensions": [round(c, 4) for c in _o.dimensions],
+    "visible": not _o.hide_get(),
+    "parent": _o.parent.name if _o.parent else None,
+    "collections": [c.name for c in _o.users_collection],
+    "modifiers": [{"name": m.name, "type": m.type} for m in _o.modifiers],
+    "material_slots": [s.material.name if s.material else None for s in _o.material_slots],
+}
+if _o.type == "MESH" and _o.data is not None:
+    _info["mesh"] = {"vertices": len(_o.data.vertices),
+                     "edges": len(_o.data.edges),
+                     "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
+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),
+}, `import os
+_path = _args["path"]
+if not os.path.isabs(_path) or not _path.lower().endswith(".blend"):
+    raise ValueError("Provide an absolute .blend path")
+if os.path.exists(_path) and not _args["overwrite"]:
+    raise ValueError("File exists; use a new path or explicitly set overwrite=true")
+bpy.ops.wm.save_as_mainfile(filepath=_path, check_existing=False)
+result = {"path": bpy.data.filepath, "saved": not bpy.data.is_dirty}`), scriptTool("bl_open_project", "Open Blender Project", "Replace the active project with an existing .blend file. Refuses unsaved changes unless discard_unsaved=true.", {
+    path: z.string().min(1), discard_unsaved: z.boolean().default(false),
+}, `import os
+_path = _args["path"]
+if not os.path.isabs(_path) or not os.path.isfile(_path) or not _path.lower().endswith(".blend"):
+    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)
+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"])
+if _obj is None:
+    raise ValueError("Object not found")
+_ok = _obj.keyframe_insert(data_path=_args["property"], frame=_args["frame"])
+result = {"inserted": _ok, "object": _obj.name, "property": _args["property"], "frame": _args["frame"]}`));
+BL_TOOLS.find(tool => tool.name === "bl_health").readOnly = true;

package/dist/transport.d.ts

@@ -0,0 +1,31 @@
+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 declare class BlenderTransport {
+    connection(): Promise<Connection>;
+    status(jobId: string, connection?: Connection): Promise<JobResult>;
+    execute(code: string, timeoutSeconds?: number): Promise<JobResult>;
+}
+export {};

package/dist/transport.js

@@ -0,0 +1,81 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+export const runtimeDirectory = () => process.env.BLENDER_MCP_RUNTIME_DIR || join(homedir(), ".higgsfield", "blender");
+const connectionSchema = z.object({
+    protocol: z.literal("higgsfield-blender/1"), pid: z.number().int().positive(),
+    port: z.number().int().min(1).max(65535), token: z.string().regex(/^[a-f0-9]{64}$/),
+});
+const jobSchema = z.object({
+    job_id: z.string(), state: z.enum(["queued", "running", "completed", "expired"]),
+    ok: z.boolean().optional(), result: z.unknown().optional(), error: z.string().optional(),
+    stdout: z.string().optional(), stderr: z.string().optional(),
+});
+async function request(connection, path, body) {
+    const response = await fetch(`http://127.0.0.1:${connection.port}${path}`, {
+        method: body === undefined ? "GET" : "POST", redirect: "error",
+        headers: { Authorization: `Bearer ${connection.token}`, "Content-Type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok)
+        throw new Error(`Blender bridge HTTP ${response.status}: ${(await response.text()).slice(0, 1000)}`);
+    return response.json();
+}
+export async function discover(directory = runtimeDirectory()) {
+    const names = await readdir(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const candidates = await Promise.all(names.filter(name => /^bridge-\d+\.json$/.test(name)).map(async (name) => {
+        try {
+            const connection = connectionSchema.parse(JSON.parse(await readFile(join(directory, name), "utf8")));
+            const health = z.object({ protocol: z.literal("higgsfield-blender/1"), pid: z.number() }).parse(await request(connection, "/health"));
+            return health.pid === connection.pid ? connection : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    return candidates.filter((value) => value !== undefined);
+}
+export class BlenderTransport {
+    async connection() {
+        const connections = await discover();
+        const selected = process.env.BLENDER_MCP_PID;
+        const matches = selected ? connections.filter(item => String(item.pid) === selected) : connections;
+        if (!matches.length)
+            throw new Error("No live Blender bridge found. Open Blender with the Higgsfield use Blender add-on enabled; run fnf-blender doctor on this computer.");
+        if (matches.length > 1)
+            throw new Error(`Multiple Blender instances: ${matches.map(item => item.pid).join(", ")}. Set BLENDER_MCP_PID to choose one before editing.`);
+        return matches[0];
+    }
+    async status(jobId, connection) {
+        return jobSchema.parse(await request(connection ?? await this.connection(), `/jobs/${encodeURIComponent(jobId)}`));
+    }
+    async execute(code, timeoutSeconds = 120) {
+        const connection = await this.connection();
+        let accepted;
+        try {
+            accepted = jobSchema.parse(await request(connection, "/execute", { code, timeout_seconds: timeoutSeconds }));
+        }
+        catch (error) {
+            throw new Error(`Submission failed; execution may have been accepted. Inspect scene state before retrying. ${String(error)}`);
+        }
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        try {
+            while (Date.now() < deadline) {
+                const result = await this.status(accepted.job_id, connection);
+                if (result.state === "completed" || result.state === "expired")
+                    return result;
+                await delay(100);
+            }
+        }
+        catch (error) {
+            throw new Error(`Lost contact with Blender; job_id=${accepted.job_id}, pid=${connection.pid}. Use bl_job_status before retrying. ${String(error)}`);
+        }
+        throw new Error(`Blender is still busy; job_id=${accepted.job_id}, pid=${connection.pid}. Execution may continue. Use bl_job_status before retrying; no automatic retry was sent.`);
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "fnf-blender-mcp",
+  "version": "0.1.0",
+  "description": "Higgsfield use Blender: local stdio MCP and authenticated loopback Blender add-on.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "fnf-blender": "dist/cli.js",
+    "fnf-blender-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "addon/**/*.py",
+    "skills",
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE",
+    "scripts/*.py"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs && python3 -m unittest discover -s tests -p \"test_*.py\"",
+    "prepack": "npm run build",
+    "test:package": "node scripts/verify-package.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/node": "^25.5.2",
+    "typescript": "^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://www.npmjs.com/package/fnf-blender-mcp",
+  "keywords": [
+    "blender",
+    "mcp",
+    "higgsfield",
+    "3d",
+    "bpy"
+  ]
+}

package/scripts/install_addon.py

@@ -0,0 +1,18 @@
+"""Install source files only; never reset or save the user's preferences."""
+import shutil
+from pathlib import Path
+import bpy
+
+if bpy.app.version < (4, 2, 0):
+    raise RuntimeError("Higgsfield use Blender requires Blender 4.2+")
+source = Path(__file__).resolve().parent.parent / "addon" / "higgsfield_use_blender"
+target = Path(bpy.utils.user_resource("SCRIPTS", path="addons", create=True)) / source.name
+marker = target / ".higgsfield-use-blender"
+if target.exists() and not marker.is_file():
+    raise RuntimeError("Refusing to overwrite an unrecognized add-on directory: %s" % target)
+target.mkdir(parents=True, exist_ok=True)
+for name in ("__init__.py", "bridge.py"):
+    shutil.copy2(source / name, target / name)
+marker.write_text("fnf-blender-mcp\n")
+print("Installed: %s" % target)
+print("Enable Higgsfield use Blender in Preferences > Add-ons, then save preferences for automatic startup.")

package/scripts/launch.py

@@ -0,0 +1,10 @@
+"""Load the bundled bridge in a new Blender session without changing preferences."""
+import sys
+from pathlib import Path
+import bpy
+
+if bpy.app.version < (4, 2, 0):
+    raise RuntimeError("Higgsfield use Blender requires Blender 4.2+")
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "addon"))
+import higgsfield_use_blender
+higgsfield_use_blender.register()

package/skills/blender-scene/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: blender-scene
+description: Create, inspect, edit and render native scenes through the local Higgsfield use Blender MCP.
+---
+
+# Local Blender workflow
+
+Call `bl_health` and `bl_get_scene_summary` before editing. Inspect important objects with `bl_get_object`. If several instances are open, select the intended PID in the server environment before mutation.
+
+Prefer the typed tools listed by this server. Use `bl_execute` for other bpy operations; assign a JSON-compatible value to `result`. Returned stdout/stderr are capped at 64 KiB each. Do not start threads that touch bpy. Use data APIs where possible; operators depend on mode, selection and UI context.
+
+Distances are in scene units (normally metres); Z is up and Euler angles are radians. Check the scene's unit settings when scale matters. Names identify objects exactly; inspect suffixes rather than assuming them.
+
+Read topic guidance through `bl_get_skill`: `modeling`, `materials`, `lighting-camera`, or `animation`, as needed.
+
+Preserve unrelated objects. Save `.blend` deliverables requested by the user with `bl_save_project`; existing files need `overwrite=true`. Before replacing the active project, save needed changes. `bl_open_project` refuses unsaved changes unless explicitly discarded.
+
+A script may partially mutate before failing. Inspect current state before retrying. A timed-out command may still be running; use its `job_id` with `bl_job_status` on the same Blender PID. Commands are not automatically retried or rolled back. Job history is in-memory and bounded; restarting Blender loses it.
+
+Verify structure with fresh reads and appearance by viewing `bl_screenshot` or `bl_render`. Screenshots require a VIEW_3D area; headless renders need a scene camera. Rendering can block Blender while it runs. Set the MCP client's tool timeout above 300 seconds for long renders.
+
+This package has no cloud generation tools or bundled bpy API/manual search. Use a separately connected Higgsfield service for generated assets; download results then call `bl_import_model` with an absolute local path. Read official version-matched Blender docs for unfamiliar APIs.

package/skills/blender-scene/references/animation.md

@@ -0,0 +1,5 @@
+# Animation
+
+Establish duration, frame rate, start/end state and intended motion before adding keys. Inspect existing animation to preserve curves outside the requested range. `bl_set_frame`, `bl_set_transform`, and `bl_insert_keyframe` cover basic object motion; use bpy for constraints, rigs, custom properties or interpolation.
+
+Check start, middle and end frames plus extrema. Verify contact, camera framing, loop seams and unwanted Euler flips. Blender animation API details vary by version; inspect live version and API before addressing actions, slots or channel bags. Save the native .blend when requested and render actual frames before claiming visual completion.

package/skills/blender-scene/references/lighting-camera.md

@@ -0,0 +1,5 @@
+# Lighting and camera
+
+Inspect the active camera, focal length and framing before changes. Use `bl_add_camera` and `bl_set_active_camera`; angles are radians. For a look-at orientation, derive rotation from target minus camera location with `to_track_quat('-Z', 'Y')`.
+
+Choose a key, fill and separation only where they improve the requested image. Light size controls softness; exposure and material roughness also affect highlight appearance. Test at low resolution and sample count with `bl_render`, view the image, then raise quality. A viewport capture is not evidence of the final camera render.

package/skills/blender-scene/references/materials.md

@@ -0,0 +1,5 @@
+# Materials
+
+Inspect existing material slots and shared datablocks before changing them. `bl_set_material` creates a new Principled material and replaces the first slot; use `bl_execute` when editing an existing shader graph or preserving several slots. Blender colors may use linear scene values; do not treat screenshot RGB values as automatically equivalent.
+
+Keep texture color spaces appropriate: color textures normally sRGB, roughness/metallic/normal/displacement Non-Color. Verify UV coverage and texture scale. Judge materials using the final render engine and lighting, including both highlight and shadow response.

package/skills/blender-scene/references/modeling.md

@@ -0,0 +1,5 @@
+# Modeling
+
+Inspect object types, dimensions, transforms and parent relationships before editing. Keep meaningful object names and editable modifiers. Work in object mode for object-level operators; restore selection when it matters. Apply scale only when a downstream operation needs it. Duplicate or save a recovery copy before broad destructive changes within the user's scope.
+
+Use `bl_add_primitive`, `bl_set_transform`, and `bl_get_object` for focused edits. For topology operations use `bl_execute` with explicit context and validate mesh counts, bounds, normals and silhouette afterward. Never clear the default scene as an incidental setup step in an existing project.

package/skills/use-blender/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: use-blender
+description: Install and connect the local Higgsfield use Blender MCP, or use it to edit native Blender scenes.
+---
+
+# Higgsfield use Blender
+
+Connect a desktop MCP client to Blender on the same computer:
+
+Desktop client → stdio → local fnf-blender-mcp → authenticated localhost HTTP → Blender Python add-on.
+
+Use **Higgsfield use Blender** as the display name and `higgsfield-use-blender` as the server identifier. No WebSocket, cloud bridge login or Higgsfield account is needed for local scene operations. Cloud asset generation uses a separate service.
+
+The runtime is distributed as the public npm package `fnf-blender-mcp`; installation requires no source checkout or build.
+
+This is a local setup command, not a generation preset. A cloud sandbox cannot install into the user's desktop Blender. First discover available local `bl_*` tools and check an existing connection before reinstalling.
+
+For setup, read [installation](references/installation.md). For connection diagnosis and edits, read [verification](references/verification.md). When these files are served by get_preset_instructions, load them with `/use-blender/references/installation` and `/use-blender/references/verification` respectively.