bambu-printer-mcp 1.1.12 → 1.1.14

package/CONTRIBUTORS.md

@@ -6,20 +6,22 @@ Thank you to everyone who builds, tests, reports problems, and shares real print
 
 | Contributor | Contribution |
 | --- | --- |
-| [Sebastian (sebas1986)](https://github.com/sebas1986) | Isolates the multi-filament CLI crash with real BambuStudio bisection, contributes per-slot colours and multi-nozzle prime-tower placement, and verifies X2D identification, status, and slicing in [#18](https://github.com/DMontgomery40/bambu-printer-mcp/pull/18). Direct X2D printing remains deferred pending the native transport. |
+| [Boardy (@boardyai)](https://x.com/boardyai) | Raises the nozzle-verification question that informs the added printer safety checks. |
+| Fable red-team review, shared by David Montgomery | Supplies archive-ambiguity reproductions and hardware-safety review findings used for plate binding, upload checks, temperature policy, and human preflight. Network/security suggestions remain outside this hardware-safety release. |
+| [Sebastian (sebas1986)](https://github.com/sebas1986) | Isolates the multi-filament CLI crash with real BambuStudio bisection, contributes per-slot colours and multi-nozzle prime-tower placement, and verifies X2D identification, status, and slicing in [#18](https://github.com/DMontgomery40/bambu-printer-mcp/pull/18). Also isolates FTPS session-host identity and supplies physical X2D USB upload/size/deletion evidence in [#24](https://github.com/DMontgomery40/bambu-printer-mcp/pull/24); that test does not establish MQTT print dispatch. |
 | [Stenslaen](https://github.com/Stenslaen) | Traces the delayed H2 crash to OTA model detection, documents a multi-day workaround, and reports unexpected state-transition crashes in [#7](https://github.com/DMontgomery40/bambu-printer-mcp/issues/7). |
 | [Alejandro Oñate (alexol91)](https://github.com/alexol91) | Reports the missing machine-template G-code and multi-filament override problems in [#12](https://github.com/DMontgomery40/bambu-printer-mcp/issues/12), with measured output and a proposed fix in [#13](https://github.com/DMontgomery40/bambu-printer-mcp/pull/13). |
 | [var-poro](https://github.com/var-poro) | Supplies P2S firmware/MQTT evidence and regression tests in [#15](https://github.com/DMontgomery40/bambu-printer-mcp/pull/15), plus profile-template resolution and inheritance tests in [#16](https://github.com/DMontgomery40/bambu-printer-mcp/pull/16). |
 | [John Randall (johntrandall)](https://github.com/johntrandall) | Captures A1 job manifests and contributes the SD-root/project-file fix in [#14](https://github.com/DMontgomery40/bambu-printer-mcp/pull/14). |
 | [Kyle Taylor (kyletaylored)](https://github.com/kyletaylored) | Contributes Claude Desktop extension packaging, prompted setup, and the writable-temp-directory fix in [#11](https://github.com/DMontgomery40/bambu-printer-mcp/pull/11). |
 | [Quinn (quinnpertuit)](https://github.com/quinnpertuit) | Investigates P2S transfer routing and contributes model-capability and serial-prefix analysis in [#9](https://github.com/DMontgomery40/bambu-printer-mcp/pull/9). The release uses the alternative P2S implementation from #15. |
-| [Vail (VailElla)](https://github.com/VailElla) | Contributes the native X2D transport, local eMMC investigation, and hardware evidence in [#10](https://github.com/DMontgomery40/bambu-printer-mcp/pull/10). That integration remains under review and is not enabled in this release. |
+| [Vail (VailElla)](https://github.com/VailElla) | Contributes the native X2D transport, local eMMC investigation, and hardware evidence in [#10](https://github.com/DMontgomery40/bambu-printer-mcp/pull/10). The optional macOS native route is integrated with shared file/state/preflight checks, complete AMS mappings, helper cancellation, and clean-install coverage. Prior hardware evidence is credited separately from this release's mocked tests. |
 
 ## Project contributors
 
 Thank you also to the existing contributors whose work the project builds on:
 
-- [David Montgomery (DMontgomery40)](https://github.com/DMontgomery40) — project maintainer; flags the FULU/Orca missing-machine-preset safety gap during article review, prompting the 1.1.11 fix.
+- [David Montgomery (DMontgomery40)](https://github.com/DMontgomery40) — project maintainer; contributes the printer-profile, temperature, and hardware-safety reports informing the shared slicing and print checks.
 - [rowbotik](https://github.com/rowbotik) — printer, AMS, slicing, and operational work across the existing release history.
 - [len-foss](https://github.com/len-foss) — project code contribution.
 - [thebitrock](https://github.com/thebitrock) — project code contribution.

package/README.md

@@ -49,7 +49,7 @@ an existing slicer before suggesting an install. For FULU/Orca CLI auto-slicing,
 require MCP 1.1.11+ and its matching installed profile tree (see guide).
 A slicer is not needed here to print a pre-sliced file. Configure the optional FULU
 BambuNetwork bridge only if I choose it, and explain its runtime/auth needs.
-X2D supports status and slicing here, but direct printing is not supported.
+X2D supports status and slicing; native printing requires macOS and a locally built helper.
 
 If this harness does not already provide code mode or an equivalent, suggest
 a compatible code-mode integration as an optional addition. It is not required;
@@ -122,7 +122,7 @@ If your agent is always on, such as OpenClaw or Hermes Agent running on a comput
 
 ## What's new in bambu-printer-mcp
 
-See the [changelog](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/CHANGELOG.md) for versioned changes. Recent releases add reliable npm and desktop-extension installs, standard Blender MCP integration, corrected P2S/A1 routing, and safer multi-filament CLI slicing. X2D status and slicing are available; **direct X2D printing remains unsupported** pending its native eMMC transport.
+See the [changelog](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/CHANGELOG.md) for versioned changes. Recent releases add reliable npm and desktop-extension installs, standard Blender MCP integration, corrected P2S/A1 routing, and safer multi-filament CLI slicing. X2D status and slicing are available, with optional native printing on macOS through the installed Bambu Studio networking plug-in.
 
 </details>
 
@@ -194,9 +194,9 @@ The optional FULU **BambuNetwork bridge** exposes `bambu_network_bridge_status`,
 - Query live AMS inventory with resolved Bambu/Orca filament profile paths via `get_printer_filaments`. Includes per-tray display names, match confidence (`high`/`medium`/`low`/`none`), resolution tier (`exact-model-nozzle`/`model`/`generic`/`unresolved`), and a summary with recommended auto-slice filament. Retries automatically when AMS data hasn't arrived yet (common on first MQTT push from idle printers).
 - List, upload, and delete files on the printer's SD card via FTPS
 - Capture a JPEG snapshot from the chamber camera. Supports A1, A1 mini, P1S, P1P (TCP-on-6000), and X1, X1C, X1E, P2S, H2, H2S, H2D, H2C, H2D Pro, X2D (RTSP via ffmpeg). Requires ffmpeg in PATH for the RTSP path.
-- Upload and print pre-sliced `.gcode.3mf` files with full plate selection and calibration flag control (recommended path — see [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md))
+- Upload and print pre-sliced `.3mf` projects with checked plate selection and calibration flags. Legacy `.gcode.3mf` routes require a single external-spool-only plate; see the [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
 - Slice through BambuStudio CLI with automatic BBL inheritance/include resolution, per-slot filament colours, and fallback prime-tower placement for multi-nozzle printers. Missing dependencies stop the slice; custom settings and saved project tower positions are preserved. Multi-colour slicing is verified by the contributor on BambuStudio 02.08.02.60 for Windows; older CLI versions have separate limitations. See [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
-- Recognize X2D status and slice with its own installed BambuStudio preset (`BAMBU_MODEL=x2d`). **Direct X2D printing is not supported yet**: the internal eMMC transport is pending. These print requests stop before slicing, uploading, or issuing printer commands. Print exported projects through a supported slicer instead.
+- Recognize X2D status and slice with its own installed BambuStudio preset (`BAMBU_MODEL=x2d`). On macOS, `print_3mf` selects the native eMMC route after resolving the model, including an elicited model. Install the optional helper as described below; Linux/Windows native print requests fail before slicing or contacting the printer. Legacy FTPS and remote G-code starts remain unsupported for X2D.
 - Parse AMS mapping from the 3MF's embedded slicer metadata (`Metadata/plate_<n>.json` + gcode filament header) and send it correctly formatted per the OpenBambuAPI spec, with correct H2S/H2D/H2C `ams_mapping2` parallel array format
 - **Auto-match AMS slots by RFID** (`auto_match_ams` flag on `print_3mf`). Resolves required `tray_info_idx` from the sliced 3MF against live AMS inventory. Handles same-SKU different-color filaments by matching on `(tray_info_idx, tray_color)` and tracking already-claimed slots. Dry-run with `resolve_3mf_ams_slots` before printing.
 - Cancel, pause, and resume in-progress print jobs via MQTT
@@ -204,6 +204,7 @@ The optional FULU **BambuNetwork bridge** exposes `bambu_network_bridge_status`,
 - Set print speed mode (`silent`/`standard`/`sport`/`ludicrous`), clear HMS/print errors, trigger AMS RFID re-read, and control H2/P2 airduct mode (`cooling`/`heating`) via MQTT
 - **Start/stop AMS filament drying** (`set_ams_drying`) on heated AMS units (AMS Pro / AMS-HT). Sends `print.ams_control` MQTT command.
 - Set nozzle and bed temperature via G-code dispatch over MQTT
+- Confirm print starts and positive manual heating through a human preflight prompt. Finished-bed clearance and hardware-error clearing require explicit human acknowledgment; see [hardware safety and headless configuration](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
 - Set fan speed (part, auxiliary, chamber) and chamber light mode (on/off/flashing) via MQTT
 - Read HMS (Health Management System) diagnostics as an MCP resource at `printer://{host}/hms` — read-only error summary from the printer, with automatic settle retry
 - Start G-code files already stored on the printer
@@ -792,12 +793,17 @@ Trigger a Bambu AMS RFID re-read for one AMS slot. This can move AMS filament; u
 
 #### set_temperature
 
-Set the target temperature for the bed or nozzle. Dispatches an M140 (bed) or M104 (nozzle) G-code command via MQTT. Valid range is 0 to 300 degrees Celsius. Accepted values for `component` are `bed`, `nozzle`, `extruder`, `tool`, and `tool0`.
+Set a checked target temperature for the bed or nozzle through MQTT. Positive targets require the printer model and fresh matching printer telemetry; nozzle heating also requires the declared loaded `material` and matching `nozzle_diameter` (default 0.4). Independent model/component and material ceilings apply. A target of zero turns the heater off without requiring material or nozzle metadata. Accepted `component` values are `bed`, `nozzle`, `extruder`, `tool`, and `tool0`.
+
+Manual nozzle heating checks the reported currently loaded AMS tray or external spool. It refuses ambiguous active-nozzle/material selection on multi-nozzle printers; use a checked sliced job or the printer's own controls there. Stop and heater-off commands cancel pending server print/heating operations. Resuming through MCP requires the same paused job inspected and started by this server instance, with fresh matching telemetry; other paused jobs remain controllable at the printer.
 
 ```json
 {
   "component": "nozzle",
   "temperature": 220,
+  "bambu_model": "p1s",
+  "material": "PLA",
+  "nozzle_diameter": 0.4,
   "host": "192.168.1.100",
   "bambu_serial": "01P00A123456789",
   "bambu_token": "your_access_token"
@@ -876,7 +882,7 @@ The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `
 2. If no G-code is found, attempts to auto-slice via the configured slicer. Profile preparation or slicing failures stop the operation before upload. See the slicing guide for tested CLI versions and combinations.
 3. Parses the sliced 3MF to extract the correct plate file and compute its MD5 hash.
 4. Reads slicer metadata and any explicit AMS selection to build the filament mapping.
-5. Uploads via `basic-ftp` to the model-specific location: SD root for H2/full-size A1, `cache/` for P1/X1/A1 mini/P2S. X2D direct printing stops before upload.
+5. Uploads via `basic-ftp` to the model-specific location: SD root for H2/full-size A1, `cache/` for P1/X1/A1 mini/P2S. X2D `print_3mf` instead uses its checked native eMMC route on macOS.
 6. Sends the correct MQTT print command for the target printer family. For H2S/H2D/H2C that means `project_file` with project-length `ams_mapping`, parallel `ams_mapping2`, and H2-compatible calibration flags.
 
 ```json
@@ -912,11 +918,25 @@ Inspect the configured FULU bridge without starting it using `{}`. Use `{"connec
 
 #### bambu_network_call
 
-Call a runtime method such as `{"method": "net.is_user_login", "payload": {}}`. The default injects the initialized agent; use `with_agent: false` for `bridge.handshake`. Raw methods can mutate runtime or printer state; use the method contract from your installed FULU build.
+Call an allowed read-only probe such as `{"method": "net.is_user_login", "payload": {}}`. The default injects the initialized agent; use `with_agent: false` for `bridge.handshake`. Raw printer mutations and unknown methods are refused; use the dedicated checked print or printer tools.
+
+#### X2D native transport (macOS)
+
+Install Bambu Studio and its networking plug-in, plus the Apple command-line developer tools (`clang++`). The plug-in is loaded at runtime and is not redistributed. In the installed `bambu-printer-mcp` package directory, run `npm run build:native`. For a global install, locate that directory with `npm root -g`; for an extracted desktop extension, run the same command in the extension directory. Rebuild after updating the package. Linux and Windows can still use status and slicing, but this native helper supports macOS only.
+
+The npm package and desktop bundle include `native/bambu-native-print.cpp` and `scripts/build-bambu-native.zsh`, never a developer's compiled binary. The server finds the built helper relative to its installed package, regardless of the launch directory. A trusted server setting `BAMBU_NATIVE_HELPER` can select an alternate executable.
+
+For X2D, `print_3mf` defaults to `connection_mode: "bambu_native"`; legacy `lan_mqtt_ftps` requests are redirected to it. Supply `ams_slots`, a complete project-level `ams_mapping`, or `auto_match_ams: true`. An external-spool job requires explicit `use_ams: false`. Raw `ams_mapping2` and nozzle/extra-option overrides are rejected before dispatch; the server derives both AMS representations from the checked structured mapping. Model/nozzle/material inspection, fresh printer-state checks, and human preflight apply before the helper receives a private snapshot. The native helper requests fresh shared printer-state authorization immediately before each print submission, including a certificate retry, and before checked heating, resume, or error-clearing commands; custom helpers must support this handshake. Stop and heater-off remain available without preflight. Native upload-only requests use the same all-plate inspection as FTPS uploads. They accept `project_name`, `preset_name`, `bed_type`, and an existing `plate_index`; AMS, nozzle, and calibration print options are rejected. Use `print_3mf` for checked print settings.
+
+The helper waits for connection/certificate exchange and retries only the initial `-4030` send once. Previous hardware testing reached `RUNNING` on X2D; this revision is validated with mocked transport regressions and clean installs, not a new physical print. `bambu_connect` is an optional macOS handoff for user review in Bambu Connect and does not start a print. Native task, heater, and error controls retain the common safety checks; raw controls cannot bypass them. Request cancellation, stop, and heater-off interrupt pending native helpers; the server waits for process exit before releasing a checked file. A command already sent to the printer cannot be recalled by cancelling the request, so verify printer state before retrying.
+
+#### x2d_native_control
+
+This optional X2D metadata tool accepts `ams_filament_setting` and `extrusion_cali_sel`, plus the read-only queries `extrusion_cali_get`, `extrusion_cali_get_result`, and `flowrate_get_result`. It validates command fields, numeric metadata, and AMS unit/slot selection. Motion, filament loading, heating, safety-setting changes, and task control are not exposed through raw JSON; use the dedicated checked tools where available. A metadata declaration does not verify the physical spool contents.
 
 #### print_3mf_bambu_network
 
-Submit a sliced project through FULU's separately configured networking runtime. `connection_type` defaults to `cloud`; LAN bridge jobs also require a printer IP and access code. `bambu_model` and a device ID are required. See [print examples and AMS requirements](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#print-through-the-bridge). A zero bridge return code confirms submission, not a physical print or direct X2D support.
+Submit a sliced project through FULU's separately configured networking runtime. `connection_type` defaults to `cloud`. Both cloud and LAN bridge jobs require a printer IP, LAN access code, matching serial/device ID, and fresh MQTT safety telemetry. File, raw AMS/nozzle mapping, and extra-option overrides cannot replace checked parameters. See [print examples and AMS requirements](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#print-through-the-bridge). A zero bridge return code confirms submission, not a physical print or direct X2D support.
 
 #### resolve_3mf_ams_slots
 

package/dist/bambu-connect.d.ts

@@ -0,0 +1,7 @@
+export type BambuConnectImportOptions = {
+    filePath: string;
+    name?: string;
+    version?: string;
+};
+export declare function buildBambuConnectImportUrl(options: BambuConnectImportOptions): string;
+export declare function importFileViaBambuConnect(options: BambuConnectImportOptions): Promise<Record<string, unknown>>;

package/dist/bambu-connect.js

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const BAMBU_CONNECT_APP_PATH = "/Applications/Bambu Connect.app";
+const BAMBU_CONNECT_SCHEME = "bambu-connect://import-file";
+function resolveImportFilePath(rawPath) {
+    const trimmed = rawPath.trim();
+    if (!trimmed) {
+        throw new Error("file_path is required.");
+    }
+    const filePath = path.resolve(trimmed);
+    if (!/\.(?:gcode|3mf)$/i.test(filePath)) {
+        throw new Error("Bambu Connect import accepts a .gcode or .3mf file.");
+    }
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+        fs.accessSync(filePath, fs.constants.R_OK);
+    }
+    catch {
+        throw new Error(`Bambu Connect import file is not readable: ${filePath}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`Bambu Connect import path is not a regular file: ${filePath}`);
+    }
+    return filePath;
+}
+function defaultImportName(filePath) {
+    const name = path.basename(filePath)
+        .replace(/\.gcode\.3mf$/i, "")
+        .replace(/\.3mf$/i, "")
+        .replace(/\.gcode$/i, "")
+        .trim();
+    return name || "Bambu print";
+}
+export function buildBambuConnectImportUrl(options) {
+    const filePath = resolveImportFilePath(options.filePath);
+    const name = options.name?.trim() || defaultImportName(filePath);
+    const version = options.version?.trim() || "1.0.0";
+    if (!version) {
+        throw new Error("version must not be empty.");
+    }
+    const url = new URL(BAMBU_CONNECT_SCHEME);
+    url.searchParams.set("path", filePath);
+    url.searchParams.set("name", name);
+    url.searchParams.set("version", version);
+    return url.toString();
+}
+export async function importFileViaBambuConnect(options) {
+    if (process.platform !== "darwin") {
+        throw new Error("Bambu Connect URL handoff is currently supported only on macOS.");
+    }
+    if (!fs.existsSync(BAMBU_CONNECT_APP_PATH)) {
+        throw new Error(`Bambu Connect is not installed at ${BAMBU_CONNECT_APP_PATH}.`);
+    }
+    const filePath = resolveImportFilePath(options.filePath);
+    const name = options.name?.trim() || defaultImportName(filePath);
+    const version = options.version?.trim() || "1.0.0";
+    const url = buildBambuConnectImportUrl({ filePath, name, version });
+    const { stdout, stderr } = await execFileAsync("/usr/bin/open", ["-a", BAMBU_CONNECT_APP_PATH, url], { encoding: "utf8", timeout: 30000 });
+    return {
+        status: "handoff_ready",
+        app: "Bambu Connect",
+        app_path: BAMBU_CONNECT_APP_PATH,
+        route: BAMBU_CONNECT_SCHEME,
+        file_path: filePath,
+        project_name: name,
+        version,
+        opened: true,
+        url,
+        stdout: String(stdout || "").trim() || undefined,
+        stderr: String(stderr || "").trim() || undefined,
+        note: "The file was handed to Bambu Connect. Review the selected printer and plate there, then start printing from Bambu Connect when ready; this handoff does not start a print by itself.",
+    };
+}

package/dist/bambu-native.d.ts

@@ -0,0 +1,66 @@
+export type BambuNativePrintOptions = {
+    host: string;
+    serial: string;
+    token: string;
+    filePath: string;
+    remoteName?: string;
+    projectName: string;
+    presetName: string;
+    plateIndex: number;
+    bedType: string;
+    useAMS: boolean;
+    amsMapping?: string;
+    amsMapping2?: string;
+    amsMappingInfo?: string;
+    nozzleMapping?: string;
+    nozzlesInfo?: string;
+    bedLeveling?: boolean;
+    flowCalibration?: boolean;
+    vibrationCalibration?: boolean;
+    layerInspect?: boolean;
+    timelapse?: boolean;
+};
+export type BambuNativeControlOptions = {
+    host: string;
+    serial: string;
+    token: string;
+    messageJson: string;
+    qos?: number;
+    flag?: number;
+};
+export type BambuNativeUpdateCallback = (line: string) => void;
+export type BambuNativeExecution = {
+    signal?: AbortSignal;
+    /** Recheck the shared stop/heater-off generation while the helper runs. */
+    assertActive?: () => void;
+    /** Read and validate fresh printer state immediately before each guarded dispatch. */
+    beforeDispatch?: () => Promise<void>;
+};
+export type BambuNativeFanCommand = {
+    fan: "part" | "auxiliary" | "right_auxiliary" | "chamber";
+    fanIndex: 1 | 2 | 3 | 10;
+    requestedSpeed: number;
+    speed: number;
+    messageJson: string;
+};
+export type BambuNativeTemperatureCommand = {
+    component: "bed" | "nozzle";
+    requestedTemperature: number;
+    temperature: number;
+    messageJson: string;
+};
+export declare function assertBambuNativeAvailable(): void;
+export declare function buildBambuNativeFanCommand(fan: string | number, speed: number, sequenceId?: string): BambuNativeFanCommand;
+export declare function buildBambuNativeTemperatureCommand(component: string, temperature: number, sequenceId?: string): BambuNativeTemperatureCommand;
+export declare function validateBambuNativeControlMessage(messageJson: string): {
+    messageJson: string;
+    command: string;
+};
+/** Public raw input is limited to metadata and read-only calibration queries. */
+export declare function validateBambuNativeMetadata(messageJson: string): string;
+export declare function sendCommandWithBambuNative(options: BambuNativeControlOptions, execution?: BambuNativeExecution): Promise<Record<string, unknown>>;
+export declare function probeBambuNative(host: string, token: string): Promise<Record<string, unknown>>;
+export declare function printWithBambuNative(options: BambuNativePrintOptions, onUpdate: BambuNativeUpdateCallback | undefined, execution: BambuNativeExecution & {
+    beforeDispatch: () => Promise<void>;
+}): Promise<Record<string, unknown>>;
+export declare function uploadWithBambuNative(options: BambuNativePrintOptions, onUpdate?: BambuNativeUpdateCallback, execution?: BambuNativeExecution): Promise<Record<string, unknown>>;