bambu-printer-mcp 1.1.27 → 1.1.29

package/dist/index.js

@@ -11,14 +11,15 @@ import { createServer as createHttpServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { STLManipulator, SLICER_TYPES, normalizeSlicerType, } from "./stl/stl-manipulator.js";
 import { BambuNetworkBridge } from "./bambu-network-bridge.js";
-import { assertBambuNativeAvailable, validateBambuNativeMetadata, buildBambuNativeFanCommand, buildBambuNativeTemperatureCommand, printWithBambuNative, sendCommandWithBambuNative, uploadWithBambuNative, } from "./bambu-native.js";
+import { assertBambuNativeAvailable, bambuNativeControlsAvailable, bambuNativeUnavailableReason, interruptNativeOperations, validateBambuNativeMetadata, buildBambuNativeFanCommand, buildBambuNativeTemperatureCommand, printWithBambuNative, sendCommandWithBambuNative, uploadWithBambuNative, } from "./bambu-native.js";
 import { importFileViaBambuConnect } from "./bambu-connect.js";
 import { BlenderMcpBridge } from "./blender-mcp-bridge.js";
-import { hasAmsMappingInput, normalizeAmsMappingObject, normalizeBridgeAmsTrayValue } from "./ams-mapping.js";
+import { bridgeAmsMapping2Entry, bridgeAmsMappingValue, externalTrayForNozzle, hasAmsMappingInput, normalizeAmsMappingObject, normalizeBridgeAmsTrayValue } from "./ams-mapping.js";
 import { analyze3MFAmsRequirements, analyze3MFPlateObjects, analyzeCollarCharm3MF, extractBambuTemplateSettings, getCollarCharmRolePolicy, parse3MF } from './3mf_parser.js';
 import { BambuImplementation, assertDirectPrintSupported } from "./printers/bambu.js";
 import { inspectPrintFile } from "./safety/print-file.js";
 import { validatePrinterState } from "./safety/printer-state.js";
+import { isDualNozzleModel } from "./safety/limits.js";
 import { withPrinterOperation, withPrintSnapshot, uniquePrintName } from "./safety/artifact.js";
 import { detectProfilesRoot } from "./slicer/profile-flatten.js";
 dotenv.config();
@@ -90,6 +91,20 @@ function resolveNozzleType(value) {
     }
     return normalized;
 }
+/** BambuStudio's nozzle_volume_type value for each tool argument value. */
+const NOZZLE_VOLUME_TYPES = { standard: "Standard", high_flow: "High Flow" };
+const VALID_NOZZLE_VOLUME_TYPES = Object.keys(NOZZLE_VOLUME_TYPES);
+/** The installed nozzle's flow type. Bambu machine presets assume Standard; the print gate compares this with the printer. */
+function resolveNozzleVolumeType(value) {
+    const raw = value === undefined || value === null || value === "" ? process.env.BAMBU_NOZZLE_VOLUME_TYPE?.trim() : value;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const normalized = String(raw).trim().toLowerCase().replace(/[\s-]+/g, "_");
+    if (!VALID_NOZZLE_VOLUME_TYPES.includes(normalized)) {
+        throw new Error(`Invalid nozzle volume type "${raw}". Valid types: ${VALID_NOZZLE_VOLUME_TYPES.join(", ")}`);
+    }
+    return NOZZLE_VOLUME_TYPES[normalized];
+}
 const VALID_BAMBUSTUDIO_CLI_BED_TYPES = ["textured_plate", "cool_plate", "engineering_plate", "hot_plate"];
 // Map model IDs to BambuStudio --load-machine preset names
 const BAMBU_MODEL_PRESETS = {
@@ -509,7 +524,7 @@ function defaultSlicerPathFor(slicerType) {
 }
 function resolveSlicerConfig(args) {
     const slicerType = normalizeSlicerType(String(args?.slicer_type || DEFAULT_SLICER_TYPE));
-    const slicerPath = String(args?.slicer_path || process.env.SLICER_PATH || defaultSlicerPathFor(slicerType));
+    const slicerPath = slicerType === "orca-slicer-api" ? "" : String(args?.slicer_path || process.env.SLICER_PATH || defaultSlicerPathFor(slicerType));
     const slicerProfile = String(args?.slicer_profile || DEFAULT_SLICER_PROFILE);
     return { slicerType, slicerPath, slicerProfile };
 }
@@ -721,18 +736,10 @@ function stringifyBridgeJson(value) {
         return value;
     return JSON.stringify(value);
 }
-function nativeAmsMapping2(mapping) {
+function nativeAmsMapping2(mapping, dualNozzle = false) {
     if (!mapping || mapping.length === 0)
         return undefined;
-    return JSON.stringify(mapping.map((value) => {
-        if (value < 0 || value === 255)
-            return { ams_id: 255, slot_id: 255 };
-        if (value === 254)
-            return { ams_id: 254, slot_id: 254 };
-        if (value >= 128)
-            return { ams_id: 128, slot_id: value - 128 };
-        return { ams_id: Math.floor(value / 4), slot_id: value % 4 };
-    }));
+    return JSON.stringify(mapping.map((value) => bridgeAmsMapping2Entry(value, dualNozzle)));
 }
 function redactPrintParams(params) {
     return {
@@ -1011,6 +1018,9 @@ class BambuPrinterMCPServer {
     resolveSlicerConfigFromArgs(args, toolName) {
         const config = resolveSlicerConfig(args);
         if (args?.slicer_path !== undefined) {
+            if (config.slicerType === "orca-slicer-api") {
+                throw new Error(`${toolName}: remote slicing uses trusted SLICER_API_URL and BAMBU_PROFILES_ROOT configuration; slicer_path is unsupported.`);
+            }
             const resolvedSlicerPath = this.resolveExecutableSelectorArg(args.slicer_path, toolName, "slicer_path");
             if (resolvedSlicerPath !== undefined) {
                 config.slicerPath = resolvedSlicerPath;
@@ -1034,12 +1044,13 @@ class BambuPrinterMCPServer {
         }
         console.error(`3MF has no gcode - auto-slicing with ${slicerType} for ${printModel}`);
         const autoSliceOptions = {
-            uptodate: true,
-            ensureOnBed: true,
-            minSave: true,
-            skipModifiedGcodes: true,
+            ...(slicerType === "orca-slicer-api" ? {} : {
+                uptodate: true, ensureOnBed: true, minSave: true, skipModifiedGcodes: true,
+            }),
+            ...(slicerType === "orca-slicer-api" ? { slicePlate: Number(args.plate_index ?? 0) + 1 } : {}),
             bedType: bedType ? resolveBambuStudioCliBedType(bedType) : undefined,
             nozzleType: resolveNozzleType(args?.nozzle_type),
+            nozzleVolumeType: resolveNozzleVolumeType(args?.nozzle_volume_type),
         };
         threeMFPath = await this.stlManipulator.sliceSTL(threeMFPath, slicerType, slicerPath, slicerProfile || undefined, undefined, printPreset, autoSliceOptions);
         console.error("Auto-sliced to: " + threeMFPath);
@@ -1048,8 +1059,9 @@ class BambuPrinterMCPServer {
     async resolveAmsPrintSettings(threeMFPath, args, host, bambuSerial, bambuToken, printModel, printNozzle) {
         const parsed3MFData = await parse3MF(threeMFPath);
         let parsedAmsMapping;
+        const trayOptions = { dualNozzle: isDualNozzleModel(printModel) };
         if (parsed3MFData.slicerConfig?.ams_mapping) {
-            const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping);
+            const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping, "ams_mapping", trayOptions);
             if (slots.length > 0) {
                 parsedAmsMapping = slots;
             }
@@ -1062,10 +1074,10 @@ class BambuPrinterMCPServer {
         if (hasUserAmsMapping) {
             let userMappingOverride;
             if (Array.isArray(args.ams_mapping)) {
-                userMappingOverride = args.ams_mapping.map((v, i) => normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`));
+                userMappingOverride = args.ams_mapping.map((v, i) => normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`, trayOptions));
             }
             else if (args.ams_mapping && typeof args.ams_mapping === 'object') {
-                userMappingOverride = normalizeAmsMappingObject(args.ams_mapping);
+                userMappingOverride = normalizeAmsMappingObject(args.ams_mapping, "ams_mapping", trayOptions);
             }
             if (userMappingOverride && userMappingOverride.length > 0) {
                 finalAmsMapping = userMappingOverride;
@@ -1074,7 +1086,7 @@ class BambuPrinterMCPServer {
             }
         }
         if (!hasUserAmsMapping && hasUserAmsSlots) {
-            const userSlots = args.ams_slots.map((slot, i) => normalizeBridgeAmsTrayValue(slot, `ams_slots[${i}]`));
+            const userSlots = args.ams_slots.map((slot, i) => normalizeBridgeAmsTrayValue(slot, `ams_slots[${i}]`, trayOptions));
             finalAmsSlots = userSlots;
             finalAmsMapping = undefined;
             useAMS = userSlots.length > 0;
@@ -1091,8 +1103,10 @@ class BambuPrinterMCPServer {
             useAMS = true;
         }
         if (args?.use_ams === false) {
-            finalAmsMapping = undefined;
-            finalAmsSlots = undefined;
+            if (!hasUserAmsMapping)
+                finalAmsMapping = undefined;
+            if (!hasUserAmsSlots)
+                finalAmsSlots = undefined;
             useAMS = false;
         }
         if ((!finalAmsMapping || finalAmsMapping.length === 0) && (!finalAmsSlots || finalAmsSlots.length === 0)) {
@@ -1162,8 +1176,16 @@ class BambuPrinterMCPServer {
                 inspection.usedFilamentPositions.forEach((position, index) => { mapping[position] = finalAmsSlots[index]; });
             }
             if (!useAMS) {
-                mapping = Array(inspection.materials.length).fill(-1);
-                inspection.usedFilamentPositions.forEach(position => { mapping[position] = 254; });
+                mapping ?? (mapping = Array(inspection.materials.length).fill(-1));
+                const dualNozzle = isDualNozzleModel(printModel);
+                for (const position of inspection.usedFilamentPositions) {
+                    if (mapping[position] === undefined || mapping[position] < 0) {
+                        mapping[position] = externalTrayForNozzle(inspection.filamentNozzleIndices?.[position], dualNozzle);
+                    }
+                    if (mapping[position] !== 254 && !(dualNozzle && mapping[position] === 255)) {
+                        throw new Error("use_ams:false requires an external-spool mapping for every used filament.");
+                    }
+                }
             }
             const requirements = { ...inspection, amsMapping: mapping, useAMS };
             const initialStatus = await this.bambu.getSafetyStatus(devIp, devId, password || bambuToken);
@@ -1172,7 +1194,7 @@ class BambuPrinterMCPServer {
             const confirmedStatus = await this.bambu.getSafetyStatus(devIp, devId, password || bambuToken);
             validatePrinterState(confirmedStatus, requirements);
             this.bambu.assertBedClearance(confirmedStatus, bedClearance);
-            const amsMapping = stringifyBridgeJson(mapping);
+            const amsMapping = stringifyBridgeJson(mapping?.map(value => bridgeAmsMappingValue(value, isDualNozzleModel(printModel))));
             const remoteFileName = uniquePrintName(threeMFPath);
             const params = {
                 dev_id: devId,
@@ -1189,7 +1211,7 @@ class BambuPrinterMCPServer {
                 ftp_file_md5: String(args?.ftp_file_md5 || ""),
                 nozzle_mapping: stringifyBridgeJson(args?.nozzle_mapping) || "",
                 ams_mapping: amsMapping || "",
-                ams_mapping2: stringifyBridgeJson(args?.ams_mapping2) || "",
+                ams_mapping2: nativeAmsMapping2(mapping, isDualNozzleModel(printModel)) || "",
                 ams_mapping_info: stringifyBridgeJson(args?.ams_mapping_info) || "",
                 nozzles_info: stringifyBridgeJson(args?.nozzles_info) || "",
                 connection_type: connectionType,
@@ -1229,7 +1251,7 @@ class BambuPrinterMCPServer {
                     host: devIp, serial: devId, token: password || bambuToken, filePath: snapshot,
                     projectName: String(params.task_name), presetName, remoteName: remoteFileName,
                     plateIndex, bedType: printBedType, useAMS,
-                    amsMapping, amsMapping2: nativeAmsMapping2(mapping),
+                    amsMapping, amsMapping2: nativeAmsMapping2(mapping, isDualNozzleModel(printModel)),
                     bedLeveling: params.task_bed_leveling,
                     flowCalibration: params.task_flow_cali,
                     vibrationCalibration: params.task_vibration_cali,
@@ -1326,12 +1348,14 @@ class BambuPrinterMCPServer {
         return this.print3mfViaBambuNetwork({ ...args, bambu_model: model, connection_type: "lan", bambu_network_method: "start_local_print" }, host, bambuSerial, bambuToken, { onUpdate, signal });
     }
     async uploadFileViaBambuNative(args, host, bambuSerial, bambuToken, onUpdate, signal) {
-        assertBambuNativeAvailable();
         if (args.print)
             throw new Error("Native upload never starts printing; use print_3mf.");
+        // Resolve and enforce the model first, as the print path does, so a
+        // non-X2D request is never told to install the native helper.
         const model = await this.resolveBambuModel(args.bambu_model);
         if (model !== "x2d")
             throw new Error("connection_mode=bambu_native is restricted to X2D.");
+        assertBambuNativeAvailable();
         const unsupported = ["use_ams", "ams_mapping", "ams_mapping2", "ams_mapping_info", "nozzle_mapping", "nozzles_info",
             "bed_leveling", "flow_calibration", "vibration_calibration", "layer_inspect", "timelapse"];
         for (const key of unsupported) {
@@ -1430,10 +1454,9 @@ class BambuPrinterMCPServer {
             throw new Error('BambuStudio CLI SuperTack bed type is not verified; use a pre-sliced 3MF for SuperTack or choose textured_plate, cool_plate, engineering_plate, or hot_plate.');
         }
         const autoSliceOptions = {
-            uptodate: true,
-            ensureOnBed: true,
-            minSave: true,
-            skipModifiedGcodes: true,
+            ...(slicerType === "orca-slicer-api" ? {} : {
+                uptodate: true, ensureOnBed: true, minSave: true, skipModifiedGcodes: true,
+            }),
             bedType,
         };
         try {
@@ -1841,6 +1864,11 @@ class BambuPrinterMCPServer {
                                     enum: [...VALID_NOZZLE_TYPES],
                                     description: "Bambu-compatible slicing: the hotend nozzle material installed on the printer (default: BAMBU_NOZZLE_TYPE, else the model preset's stock nozzle, usually stainless_steel). Printing compares it with the printer's reported nozzle."
                                 },
+                                nozzle_volume_type: {
+                                    type: "string",
+                                    enum: [...VALID_NOZZLE_VOLUME_TYPES],
+                                    description: "Bambu-compatible slicing: the flow type of the nozzle installed on the printer (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard). high_flow uses the presets' High Flow values, such as the filament's High Flow max volumetric speed, and is refused if the machine preset has no High Flow variant. Printing compares it with the printer's reported nozzle flow."
+                                },
                                 use_printer_filaments: { type: "boolean", description: "When true, and no explicit slicer profile or load_filaments override is provided, use the printer's current or first loaded AMS filament as the slicer filament profile." },
                                 host: { type: "string", description: "Hostname or IP of the printer (default: value from env)" },
                                 bambu_serial: { type: "string", description: "Serial number (default: value from env)" },
@@ -1896,6 +1924,11 @@ class BambuPrinterMCPServer {
                                     enum: [...VALID_NOZZLE_TYPES],
                                     description: "Bambu-compatible slicing: the hotend nozzle material installed on the printer (default: BAMBU_NOZZLE_TYPE, else the model preset's stock nozzle, usually stainless_steel). Printing compares it with the printer's reported nozzle."
                                 },
+                                nozzle_volume_type: {
+                                    type: "string",
+                                    enum: [...VALID_NOZZLE_VOLUME_TYPES],
+                                    description: "Bambu-compatible slicing: the flow type of the nozzle installed on the printer (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard). high_flow uses the presets' High Flow values, such as the filament's High Flow max volumetric speed, and is refused if the machine preset has no High Flow variant. Printing compares it with the printer's reported nozzle flow."
+                                },
                                 use_printer_filaments: { type: "boolean", description: "When true, and no explicit slicer profile or load_filaments override is provided, use the printer's current or first loaded AMS filament as the slicer filament profile. Template 3MF process settings can still be used at the same time." },
                                 uptodate: { type: "boolean", description: "Refresh 3MF preset configs to match the latest BambuStudio version. Use when slicing downloaded or older 3MF files to prevent stale-config failures." },
                                 repetitions: { type: "number", description: "Print N identical copies of the model. Each copy gets its own plate placement. Example: 3 prints three copies." },
@@ -1916,7 +1949,7 @@ class BambuPrinterMCPServer {
                                 rotate_y: { type: "number", description: "Rotate the model around the Y-axis by this many degrees before slicing. Useful for reorienting prints for better layer adhesion." },
                                 min_save: { type: "boolean", description: "Write a smaller output 3MF by omitting non-essential metadata. Reduces file size for faster FTP upload to the printer." },
                                 skip_modified_gcodes: { type: "boolean", description: "Strip custom start/end gcodes embedded in the 3MF. Recommended for downloaded 3MFs since custom gcodes from other users' profiles may be unsafe for your printer." },
-                                slice_plate: { type: "number", description: "Which plate index to slice. 0 = all plates (default). Use 1, 2, etc. to slice only a specific plate in multi-plate 3MF projects." }
+                                slice_plate: { type: "number", description: "Which plate index to slice. 0 = all plates for local slicers; remote slicing defaults to plate 1 and rejects 0. Use 1, 2, etc. to slice only a specific plate in multi-plate 3MF projects." }
                             },
                             required: ["stl_path", "bambu_model"]
                         }
@@ -2002,6 +2035,7 @@ class BambuPrinterMCPServer {
                                 password: { type: "string", description: "Printer password/access code override for LAN/local bridge methods." },
                                 bed_type: { type: "string", enum: ["textured_plate", "cool_plate", "engineering_plate", "hot_plate", "supertack_plate"], description: "Bed plate type currently installed (default: textured_plate)." },
                                 nozzle_type: { type: "string", enum: [...VALID_NOZZLE_TYPES], description: "Installed nozzle material, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_TYPE, else the preset's stock nozzle)." },
+                                nozzle_volume_type: { type: "string", enum: [...VALID_NOZZLE_VOLUME_TYPES], description: "Installed nozzle flow type, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard)." },
                                 plate_index: { type: "number", description: "Zero-based plate index to print from the sliced 3MF; converted to FULU's one-based PrintParams plate_index." },
                                 project_name: { type: "string", description: "Optional project name sent in FULU PrintParams; defaults to the 3MF filename without extension." },
                                 preset_name: { type: "string", description: "Optional preset name sent in FULU PrintParams; defaults to project plus one-based plate index." },
@@ -2018,8 +2052,8 @@ class BambuPrinterMCPServer {
                                 nozzle_diameter: { type: "string", description: "Nozzle diameter in mm for auto-slicing (default: 0.4)." },
                                 nozzle_diameters: { type: "array", minItems: 1, maxItems: 2, items: { type: "number", enum: [0.2, 0.4, 0.6, 0.8] }, description: "Complete per-nozzle diameters for pre-sliced jobs, e.g. [0.4, 0.6]. Omit to verify file metadata against every reported nozzle; cannot combine with nozzle_diameter." },
                                 use_ams: { type: "boolean", description: "Whether to use the AMS; defaults to auto-detect from the 3MF mapping." },
-                                ams_mapping: { type: "array", description: "AMS slot mapping array used by both local MCP printing and FULU PrintParams.", items: { type: "number" } },
-                                ams_slots: { type: "array", description: "Per-used-filament AMS slot list, matching the local LAN print path.", items: { type: "number" } },
+                                ams_mapping: { type: "array", description: "AMS slot mapping array used by both local MCP printing and FULU PrintParams. Same tray values as print_3mf: 254 = external spool; on dual-nozzle printers 254 = left/deputy nozzle external and 255 = right/main nozzle external.", items: { type: "number" } },
+                                ams_slots: { type: "array", description: "Per-used-filament AMS slot list, matching the local LAN print path (254/255 external spool rules as in print_3mf).", items: { type: "number" } },
                                 ams_mapping_bridge: { type: "string", description: "Raw JSON string override for FULU PrintParams ams_mapping when the automatic array is not enough." },
                                 ams_mapping2: { type: "string", description: "Raw JSON string for FULU PrintParams ams_mapping2, matching OrcaSlicer-bambulab's v1 AMS mapping field." },
                                 ams_mapping_info: { type: "string", description: "Raw JSON string for FULU PrintParams ams_mapping_info, matching OrcaSlicer-bambulab's detailed AMS mapping field." },
@@ -2265,7 +2299,7 @@ class BambuPrinterMCPServer {
                     },
                     {
                         name: "reread_ams_rfid",
-                        description: "Trigger a Bambu AMS RFID re-read for one AMS slot. X2D on macOS uses the native official plug-in route. This can move AMS filament; use only when the printer is idle and unloaded.",
+                        description: "Trigger a Bambu AMS RFID re-read for one AMS slot. X2D on macOS, or Linux with the native helper installed, uses the native official plug-in route. This can move AMS filament; use only when the printer is idle and unloaded.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -2298,7 +2332,7 @@ class BambuPrinterMCPServer {
                     },
                     {
                         name: "set_fan_speed",
-                        description: "Set a Bambu printer fan speed percentage. X2D on macOS uses the installed Bambu networking plug-in without UI automation; other models use MQTT.",
+                        description: "Set a Bambu printer fan speed percentage. X2D on macOS, or Linux with the native helper installed, uses Bambu's networking plug-in without UI automation; other models use MQTT.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -2357,7 +2391,7 @@ class BambuPrinterMCPServer {
                     },
                     {
                         name: "set_ams_drying",
-                        description: "Start or stop the AMS filament drying cycle. X2D on macOS uses the native official plug-in route and supports AMS-HT id 128.",
+                        description: "Start or stop the AMS filament drying cycle. X2D on macOS, or Linux with the native helper installed, uses the native official plug-in route and supports AMS-HT id 128.",
                         inputSchema: {
                             type: "object",
                             properties: {
@@ -2429,6 +2463,11 @@ class BambuPrinterMCPServer {
                                     enum: [...VALID_NOZZLE_TYPES],
                                     description: "Installed nozzle material, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_TYPE, else the preset's stock nozzle)."
                                 },
+                                nozzle_volume_type: {
+                                    type: "string",
+                                    enum: [...VALID_NOZZLE_VOLUME_TYPES],
+                                    description: "Installed nozzle flow type, used when the 3MF must be auto-sliced (default: BAMBU_NOZZLE_VOLUME_TYPE, else standard)."
+                                },
                                 host: { type: "string", description: "Hostname or IP of the printer (default: value from env)" },
                                 bambu_serial: { type: "string", description: "Serial number (default: value from env)" },
                                 bambu_token: { type: "string", description: "Access token (default: value from env)" },
@@ -2442,12 +2481,12 @@ class BambuPrinterMCPServer {
                                 use_ams: { type: "boolean", description: "Whether to use the AMS (default: auto-detect from 3MF)" },
                                 ams_mapping: {
                                     type: "array",
-                                    description: "Project-level AMS mapping array. Position = project filament index, value = absolute AMS tray (0-3=AMS 0, 4-7=AMS 1, 8-11=AMS 2, 128+=AMS-HT, 254=external, -1=unused). Prefer ams_slots unless you know the project-level layout.",
+                                    description: "Project-level AMS mapping array. Position = project filament index, value = absolute AMS tray (0-3=AMS 0, 4-7=AMS 1, 8-11=AMS 2, 128+=AMS-HT, 254=external, -1=unused). On dual-nozzle printers (H2D, H2D Pro, H2C, X2D) 254 is the LEFT/deputy nozzle external spool and 255 the RIGHT/main nozzle external spool, matching Bambu Studio's virtual tray ids; the gcode header's filament_map (1=left, 2=right) says which nozzle each filament was sliced for. Prefer ams_slots unless you know the project-level layout.",
                                     items: { type: "number" }
                                 },
                                 ams_slots: {
                                     type: "array",
-                                    description: "Preferred AMS input: one absolute tray index per USED filament in plate order, e.g. [1] for a single-filament print pulling from AMS 0 slot 1. Expanded to project-level ams_mapping automatically from the 3MF's plate_N.json and gcode header.",
+                                    description: "Preferred AMS input: one absolute tray index per USED filament in plate order, e.g. [1] for a single-filament print pulling from AMS 0 slot 1. Use 254 for the external spool (on dual-nozzle printers: 254 = left/deputy nozzle external, 255 = right/main nozzle external). Expanded to project-level ams_mapping automatically from the 3MF's plate_N.json and gcode header.",
                                     items: { type: "number" }
                                 },
                                 auto_match_ams: {
@@ -2618,9 +2657,42 @@ class BambuPrinterMCPServer {
             const host = String(args?.host || DEFAULT_HOST);
             const bambuSerial = String(args?.bambu_serial || DEFAULT_BAMBU_SERIAL);
             const bambuToken = String(args?.bambu_token || DEFAULT_BAMBU_TOKEN);
-            const nativeControls = process.platform === "darwin" &&
-                (bambuSerial.trim().toUpperCase().startsWith("20P") ||
-                    (DEFAULT_BAMBU_MODEL === "x2d" && bambuSerial === DEFAULT_BAMBU_SERIAL));
+            const x2dTarget = bambuSerial.trim().toUpperCase().startsWith("20P") ||
+                (DEFAULT_BAMBU_MODEL === "x2d" && bambuSerial === DEFAULT_BAMBU_SERIAL);
+            // Resolved lazily: the Linux availability check reads files, and most
+            // tools (status, slicing, STL) never need it.
+            // One resolution per request; null means native X2D controls are usable.
+            let nativeUnavailable;
+            const nativeUnavailableReason = () => (nativeUnavailable ?? (nativeUnavailable = x2dTarget ? bambuNativeUnavailableReason() ?? null : "The selected printer is not an X2D."));
+            const nativeControls = () => nativeUnavailableReason() === null;
+            // Linux sent X2D stop and heater-off over MQTT before the native route
+            // existed. Send them over both routes there: a stuck helper must not
+            // delay an emergency control, and a repeated stop or heater-off is
+            // harmless. The immediate MQTT send can precede the exit of an older
+            // print or heating helper that then still dispatches, so MQTT is sent
+            // again once every older helper for this printer has exited, and only
+            // that send counts. Either counted route succeeding is success. macOS
+            // stays native-only.
+            const linuxEmergency = (native, mqtt) => async () => {
+                if (process.platform !== "linux")
+                    return native();
+                const [nativeResult, immediateResult, mqttResult] = await Promise.allSettled([
+                    native(),
+                    mqtt(),
+                    interruptNativeOperations(bambuSerial).then(() => mqtt()),
+                ]);
+                const reason = (result) => result.status === "rejected" ? (result.reason instanceof Error ? result.reason.message : String(result.reason)) : undefined;
+                if (nativeResult.status === "rejected" && mqttResult.status === "rejected") {
+                    throw new Error(`native route: ${reason(nativeResult)}; MQTT route: ${reason(mqttResult)}`);
+                }
+                const state = (result) => result.status === "fulfilled" ? "sent" : "failed";
+                return {
+                    status: "success",
+                    routes: { native: state(nativeResult), mqtt: state(mqttResult), mqtt_immediate: state(immediateResult) },
+                    ...(reason(nativeResult) ? { native_error: reason(nativeResult) } : {}),
+                    ...(reason(mqttResult) ? { mqtt_error: reason(mqttResult) } : {}),
+                };
+            };
             const requestedTemplateDir = typeof args?.template_dir === "string" && args.template_dir.trim().length > 0
                 ? String(args.template_dir)
                 : undefined;
@@ -2822,19 +2894,19 @@ class BambuPrinterMCPServer {
                         break;
                     }
                     case "cancel_print":
-                        result = await this.bambu.cancelJob(host, bambuSerial, bambuToken, nativeControls
-                            ? () => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
-                                messageJson: JSON.stringify({ print: { command: "stop", param: "", sequence_id: String(Date.now()) } }), qos: 1 })
+                        result = await this.bambu.cancelJob(host, bambuSerial, bambuToken, nativeControls()
+                            ? linuxEmergency(() => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
+                                messageJson: JSON.stringify({ print: { command: "stop", param: "", sequence_id: String(Date.now()) } }), qos: 1 }), () => this.bambu.sendStopOverMqtt(host, bambuSerial, bambuToken))
                             : undefined);
                         break;
                     case "pause_print":
-                        result = await this.bambu.pauseJob(host, bambuSerial, bambuToken, nativeControls
+                        result = await this.bambu.pauseJob(host, bambuSerial, bambuToken, nativeControls()
                             ? () => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
                                 messageJson: JSON.stringify({ print: { command: "pause", param: "", sequence_id: String(Date.now()) } }), qos: 1 })
                             : undefined);
                         break;
                     case "resume_print":
-                        result = await this.bambu.resumeJob(host, bambuSerial, bambuToken, nativeControls
+                        result = await this.bambu.resumeJob(host, bambuSerial, bambuToken, nativeControls()
                             ? (assertActive, beforeDispatch) => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
                                 messageJson: JSON.stringify({ print: { command: "resume", param: "", sequence_id: String(Date.now()) } }), qos: 1 }, { signal: extra.signal, assertActive, beforeDispatch })
                             : undefined);
@@ -2843,8 +2915,9 @@ class BambuPrinterMCPServer {
                         if (!args?.message_json) {
                             throw new Error("Missing required parameter: message_json");
                         }
-                        if (!nativeControls) {
-                            throw new Error("x2d_native_control is restricted to a selected X2D printer on macOS.");
+                        if (!nativeControls()) {
+                            throw new Error("x2d_native_control is restricted to a selected X2D printer on macOS, or on Linux with the native helper installed. " +
+                                nativeUnavailableReason());
                         }
                         const messageJson = validateBambuNativeMetadata(String(args.message_json));
                         result = await sendNativeCommand({
@@ -2858,7 +2931,7 @@ class BambuPrinterMCPServer {
                         break;
                     }
                     case "clear_hms_errors":
-                        result = await this.bambu.clearHmsErrors(host, bambuSerial, bambuToken, nativeControls
+                        result = await this.bambu.clearHmsErrors(host, bambuSerial, bambuToken, nativeControls()
                             ? (assertActive, beforeDispatch) => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
                                 messageJson: JSON.stringify({ print: { command: "clean_print_error", param: "", sequence_id: String(Date.now()) } }), qos: 1 }, { signal: extra.signal, assertActive, beforeDispatch })
                             : undefined);
@@ -2867,7 +2940,7 @@ class BambuPrinterMCPServer {
                         if (!args?.mode) {
                             throw new Error("Missing required parameter: mode");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const normalized = String(args.mode).trim().toLowerCase();
                             const mode = normalized === "silent" ? 1
                                 : normalized === "standard" ? 2
@@ -2894,7 +2967,7 @@ class BambuPrinterMCPServer {
                         if (!args?.mode) {
                             throw new Error("Missing required parameter: mode");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const mode = String(args.mode).trim().toLowerCase();
                             if (mode !== "cooling" && mode !== "heating") {
                                 throw new Error("Airduct mode must be one of: cooling, heating.");
@@ -2921,7 +2994,7 @@ class BambuPrinterMCPServer {
                         if (args?.ams_id === undefined || args?.slot_id === undefined) {
                             throw new Error("Missing required parameters: ams_id and slot_id");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const amsId = Number(args.ams_id);
                             const slotId = Number(args.slot_id);
                             if ((!Number.isInteger(amsId) || (amsId < 0 || amsId > 3)) && amsId !== 128) {
@@ -2958,9 +3031,14 @@ class BambuPrinterMCPServer {
                         const heaterModel = args.temperature === 0
                             ? String(args.bambu_model || DEFAULT_BAMBU_MODEL).trim().toLowerCase()
                             : await this.resolveBambuModel(args.bambu_model);
-                        result = await this.bambu.setTemperature(host, bambuSerial, bambuToken, String(args.component), args.temperature, heaterModel || undefined, args?.material !== undefined ? String(args.material) : undefined, Number(args?.nozzle_diameter ?? DEFAULT_NOZZLE_DIAMETER), (args.temperature === 0 ? nativeControls : heaterModel === "x2d" && process.platform === "darwin")
-                            ? (heater, target, assertActive, beforeDispatch) => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
-                                messageJson: buildBambuNativeTemperatureCommand(heater, target).messageJson }, { signal: extra.signal, assertActive, beforeDispatch })
+                        result = await this.bambu.setTemperature(host, bambuSerial, bambuToken, String(args.component), args.temperature, heaterModel || undefined, args?.material !== undefined ? String(args.material) : undefined, Number(args?.nozzle_diameter ?? DEFAULT_NOZZLE_DIAMETER), (args.temperature === 0 ? nativeControls() : heaterModel === "x2d" && bambuNativeControlsAvailable())
+                            ? (heater, target, assertActive, beforeDispatch) => {
+                                const native = () => sendNativeCommand({ host, serial: bambuSerial, token: bambuToken,
+                                    messageJson: buildBambuNativeTemperatureCommand(heater, target).messageJson }, { signal: extra.signal, assertActive, beforeDispatch });
+                                return target === 0
+                                    ? linuxEmergency(native, () => this.bambu.sendHeaterOffOverMqtt(host, bambuSerial, bambuToken, heater))()
+                                    : native();
+                            }
                             : undefined);
                         break;
                     }
@@ -2968,7 +3046,7 @@ class BambuPrinterMCPServer {
                         if (!args?.fan || args?.speed === undefined) {
                             throw new Error("Missing required parameters: fan and speed");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const status = await this.bambu.getStatus(host, bambuSerial, bambuToken);
                             const printerState = String(status?.raw?.gcode_state ?? status?.raw?.print?.gcode_state ?? status?.gcode_state ?? status?.status ?? "").toUpperCase();
                             if (printerState === "RUNNING" && args?.confirm_during_print !== true) {
@@ -2996,7 +3074,7 @@ class BambuPrinterMCPServer {
                         if (!args?.light || !args?.mode) {
                             throw new Error("Missing required parameters: light and mode");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const light = String(args.light).trim();
                             const mode = String(args.mode).trim().toLowerCase();
                             if (light !== "chamber_light" && light !== "chamber_light2") {
@@ -3031,7 +3109,7 @@ class BambuPrinterMCPServer {
                         if (!Array.isArray(args?.object_ids)) {
                             throw new Error("Missing required parameter: object_ids");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const objectIds = args.object_ids.map((id) => Number(id));
                             if (objectIds.length === 0 || objectIds.some((id) => !Number.isInteger(id) || id < 0)) {
                                 throw new Error("object_ids must contain one or more non-negative integers.");
@@ -3054,7 +3132,7 @@ class BambuPrinterMCPServer {
                         if (!args?.action || args?.ams_id === undefined) {
                             throw new Error("Missing required parameters: action and ams_id");
                         }
-                        if (nativeControls) {
+                        if (nativeControls()) {
                             const action = String(args.action).trim().toLowerCase();
                             const amsId = Number(args.ams_id);
                             if (action !== "start" && action !== "stop") {
@@ -3164,6 +3242,7 @@ class BambuPrinterMCPServer {
                             sliceBambuOptions.filamentColours = parseFilamentColours(String(args.filament_colours));
                         sliceBambuOptions.bedType = resolveBambuStudioCliBedType(args?.bed_type);
                         sliceBambuOptions.nozzleType = resolveNozzleType(args?.nozzle_type);
+                        sliceBambuOptions.nozzleVolumeType = resolveNozzleVolumeType(args?.nozzle_volume_type);
                         if (args?.enable_timelapse !== undefined)
                             sliceBambuOptions.enableTimelapse = Boolean(args.enable_timelapse);
                         if (args?.allow_mix_temp !== undefined)
@@ -3244,6 +3323,7 @@ class BambuPrinterMCPServer {
                             sliceBambuOptions.filamentColours = parseFilamentColours(String(args.filament_colours));
                         sliceBambuOptions.bedType = resolveBambuStudioCliBedType(args?.bed_type);
                         sliceBambuOptions.nozzleType = resolveNozzleType(args?.nozzle_type);
+                        sliceBambuOptions.nozzleVolumeType = resolveNozzleVolumeType(args?.nozzle_volume_type);
                         if (args?.enable_timelapse !== undefined)
                             sliceBambuOptions.enableTimelapse = Boolean(args.enable_timelapse);
                         if (args?.allow_mix_temp !== undefined)
@@ -3341,12 +3421,12 @@ class BambuPrinterMCPServer {
                             }
                             console.error(`3MF has no gcode — auto-slicing with ${slicerType} for ${printModel}`);
                             const autoSliceOptions = {
-                                uptodate: true,
-                                ensureOnBed: true,
-                                minSave: true,
-                                skipModifiedGcodes: true,
+                                ...(slicerType === "orca-slicer-api" ? { slicePlate: plateIndex + 1 } : {
+                                    uptodate: true, ensureOnBed: true, minSave: true, skipModifiedGcodes: true,
+                                }),
                                 bedType: printBedType,
                                 nozzleType: resolveNozzleType(args?.nozzle_type),
+                                nozzleVolumeType: resolveNozzleVolumeType(args?.nozzle_volume_type),
                             };
                             if (!explicitSlicerProfile) {
                                 try {
@@ -3365,9 +3445,10 @@ class BambuPrinterMCPServer {
                         }
                         const parsed3MFData = await parse3MF(threeMFPath);
                         const isH2Print = H2_BAMBU_MODELS.has(printModel);
+                        const trayOptions = { dualNozzle: isDualNozzleModel(printModel) };
                         let parsedAmsMapping;
                         if (!isH2Print && parsed3MFData.slicerConfig?.ams_mapping) {
-                            const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping);
+                            const slots = normalizeAmsMappingObject(parsed3MFData.slicerConfig.ams_mapping, "ams_mapping", trayOptions);
                             if (slots.length > 0) {
                                 parsedAmsMapping = slots;
                             }
@@ -3380,10 +3461,10 @@ class BambuPrinterMCPServer {
                         if (hasUserAmsMapping) {
                             let userMappingOverride;
                             if (Array.isArray(args.ams_mapping)) {
-                                userMappingOverride = args.ams_mapping.map((v, i) => normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`));
+                                userMappingOverride = args.ams_mapping.map((v, i) => normalizeBridgeAmsTrayValue(v, `ams_mapping[${i}]`, trayOptions));
                             }
                             else if (args.ams_mapping && typeof args.ams_mapping === 'object') {
-                                userMappingOverride = normalizeAmsMappingObject(args.ams_mapping);
+                                userMappingOverride = normalizeAmsMappingObject(args.ams_mapping, "ams_mapping", trayOptions);
                             }
                             if (userMappingOverride && userMappingOverride.length > 0) {
                                 finalAmsMapping = userMappingOverride;
@@ -3424,8 +3505,10 @@ class BambuPrinterMCPServer {
                             }
                         }
                         if (args?.use_ams === false) {
-                            finalAmsMapping = undefined;
-                            finalAmsSlots = undefined;
+                            if (!hasUserAmsMapping)
+                                finalAmsMapping = undefined;
+                            if (!hasUserAmsSlots)
+                                finalAmsSlots = undefined;
                             useAMS = false;
                         }
                         if ((!finalAmsMapping || finalAmsMapping.length === 0) && (!finalAmsSlots || finalAmsSlots.length === 0)) {

package/dist/printers/bambu.d.ts

@@ -26,6 +26,13 @@ interface BambuPrintOptionsInternal {
     amsSlots?: number[];
     md5?: string;
 }
+/** What the human confirmed in confirmPrintPreflight, checked again before dispatch. */
+export type PrintPreflight = {
+    finishedJob?: string;
+    serial: string;
+    model: string;
+    notices: string[];
+};
 export declare class BambuImplementation {
     private readonly confirm?;
     private printerStore;
@@ -34,8 +41,14 @@ export declare class BambuImplementation {
     constructor(confirm?: ((message: string) => Promise<boolean>) | undefined);
     confirmHardwareAction(message: string, physicalCheck?: boolean): Promise<void>;
     private finishedJobIdentity;
-    confirmPrintPreflight(serial: string, status: any, inspection: Awaited<ReturnType<typeof inspectPrintFile>>): Promise<string | undefined>;
-    assertBedClearance(status: any, confirmedFinishedJob: string | undefined): void;
+    /**
+     * The human print confirmation. Its result goes to assertBedClearance at
+     * every later state check of the same print, which stops the print if the
+     * situation the human confirmed has changed.
+     */
+    confirmPrintPreflight(serial: string, status: any, inspection: Awaited<ReturnType<typeof inspectPrintFile>>): Promise<PrintPreflight>;
+    /** Stop a print whose confirmed situation changed: a newly finished job, or a hidden HMS notice the preflight did not name. */
+    assertBedClearance(status: any, preflight: PrintPreflight): void;
     private getPrinter;
     /** Internal handoff from a successful inspected transport; never exposed as an MCP tool. */
     recordCheckedJob(host: string, serial: string, remotePath: string, requirements: PrinterStateRequirements): void;
@@ -47,6 +60,10 @@ export declare class BambuImplementation {
     print3mf(host: string, serial: string, token: string, options: BambuPrintOptionsInternal): Promise<any>;
     private print3mfPrepared;
     cancelJob(host: string, serial: string, token: string, dispatch?: () => Promise<any>): Promise<any>;
+    /** Raw MQTT stop for routes that already ran the shared cancellation steps. */
+    sendStopOverMqtt(host: string, serial: string, token: string): Promise<any>;
+    /** Raw MQTT heater-off; switching off needs no material or model declaration. */
+    sendHeaterOffOverMqtt(host: string, serial: string, token: string, heater: "bed" | "nozzle"): Promise<any>;
     pauseJob(host: string, serial: string, token: string, dispatch?: () => Promise<any>): Promise<any>;
     resumeJob(host: string, serial: string, token: string, dispatch?: (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>): Promise<any>;
     clearHmsErrors(host: string, serial: string, token: string, dispatch?: (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>): Promise<any>;
@@ -54,6 +71,16 @@ export declare class BambuImplementation {
     setAirductMode(host: string, serial: string, token: string, mode: string): Promise<any>;
     rereadAmsRfid(host: string, serial: string, token: string, amsId: number, slotId: number): Promise<any>;
     setTemperature(host: string, serial: string, token: string, component: string, temperature: unknown, bambuModel?: string, material?: string, nozzleDiameter?: number, dispatch?: (heater: "bed" | "nozzle", target: number, assertActive: () => void, beforeDispatch?: () => Promise<void>) => Promise<any>): Promise<{
+        routes: any;
+        native_error: any;
+        mqtt_error: any;
+        status: string;
+        message: string;
+        command: string;
+    } | {
+        routes?: undefined;
+        native_error?: undefined;
+        mqtt_error?: undefined;
         status: string;
         message: string;
         command: string;