bambu-printer-mcp 1.1.11 → 1.1.13

package/CONTRIBUTORS.md

@@ -6,6 +6,8 @@ Thank you to everyone who builds, tests, reports problems, and shares real print
 
 | Contributor | Contribution |
 | --- | --- |
+| [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). Direct X2D printing remains deferred pending the native transport. |
 | [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). |
@@ -19,7 +21,7 @@ Thank you to everyone who builds, tests, reports problems, and shares real print
 
 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

@@ -13,6 +13,8 @@
 
 A Bambu Lab-focused MCP server for controlling Bambu printers, manipulating STL files, and managing end-to-end 3MF print workflows from Claude Desktop, Claude Code, or any MCP-compatible client.
 
+**[Browse the documentation site](https://dmontgomery40.github.io/bambu-printer-mcp/)** for searchable setup guides, slicing and AMS guidance, and the full tool reference. It is generated from this README and the docs folder.
+
 Built with help from our [contributors](./CONTRIBUTORS.md). Huge thanks to everyone sharing fixes, careful bug reports, and real printer testing!
 
 This is a stripped-down, Bambu-only fork of [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server). All OctoPrint, Klipper, Duet, Repetier, Prusa Connect, and Creality Cloud support has been removed. What remains is a focused, lean implementation for Bambu Lab hardware.
@@ -60,6 +62,43 @@ worked and whether I need to restart or reload the harness.
 
 [Setup reference](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md) · [FULU guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md) · [Optional code mode](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md#optional-code-mode)
 
+## What to ask your agent
+
+Ask for the result you want, not the steps. Current models plan across tools: they search the web, read photos, look up exact dimensions, edit models, slice, and print. Expect a question or two when a choice matters, such as which filament to use or whether to start the print.
+
+This server provides the printer, slicing, AMS, and mesh tools. Web search, photos, and Blender edits come from your agent and its other connections, such as a [Blender MCP server](#blender-mcp). Printing a model your agent edited uses CLI slicing with your installed slicer presets; see the [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
+
+### Start from anything
+
+- **"Here's a phone stand on MakerWorld. Make it fit the new iPhone and print it in black."**\
+  Your agent looks up Apple's published dimensions, adjusts the stand in Blender, slices it for your printer, and finds the AMS tray with black filament.
+- **"I want one of these."** *(with a photo of a planter you saw at a café)*\
+  It works out the shape and size from the photo, finds or models a matching design, and asks about anything the photo can't show.
+- **"Can you print a replacement?"** *(with a photo of a snapped dishwasher rack clip)*\
+  It asks for a measurement or two where the fit matters, models the part, and prints it in a loaded material that suits the job.
+
+### From anywhere, while it prints
+
+If your agent is always on, such as OpenClaw or Hermes Agent running on a computer at home, message it from Telegram or any other chat app. For direct LAN printing, the server runs on the printer's local network; you don't have to.
+
+- **"How's the print going? Send me a picture."**\
+  It reports progress and time remaining, and sends a snapshot from the chamber camera.
+- **"The corner is lifting. Pause it."**\
+  It pauses the job so you can decide whether to resume or cancel.
+- **"One of the parts came loose. Skip it and keep printing the rest."**\
+  It finds that object on the plate and skips only that one.
+- **"Start drying the PETG so it's ready when I get home."**\
+  On a heated AMS, it starts the drying cycle for the unit holding that spool.
+
+### Before you print
+
+- **"Take a picture and make sure the bed is clear, then start the bracket I sliced last night."**\
+  It checks the camera image before it sends the job.
+- **"What's loaded in the AMS? Print this in whatever black I have."**\
+  It reads the live AMS inventory and matches the file's filaments to your trays.
+- **"Are there any errors on the printer?"**\
+  It reads the printer's HMS diagnostics and explains them.
+
 <details>
 <summary><strong>Start here</strong></summary>
 
@@ -69,6 +108,7 @@ worked and whether I need to restart or reload the harness.
 |---|---|
 | Use open-source slicing and a cloud-free print workflow | [FULU setup: slicer, LAN, and optional bridge](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md) |
 | Connect this MCP to my agent | [Copy the setup request](#set-up-with-your-agent) |
+| See what my agent can do with it | [What to ask your agent](#what-to-ask-your-agent) |
 | Troubleshoot setup or configure it manually | [Installation, environment variables, and LAN reference](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md) |
 | Prepare a printable file or troubleshoot slicing | [Slicing guide and model routing](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md) |
 | Choose filament trays or inspect a printer | [AMS setup](#ams-automatic-material-system-setup) and [printer tools](#printer-control-tools) |
@@ -96,6 +136,7 @@ See the [changelog](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main
 - [FULU and open-source printing](#fulu-and-open-source-printing)
 - [Features](#features)
 - [Set up with your agent](#set-up-with-your-agent)
+- [What to ask your agent](#what-to-ask-your-agent)
 - [AMS (Automatic Material System) Setup](#ams-automatic-material-system-setup)
 - [Bambu Communication Notes (MQTT and FTP)](#bambu-communication-notes-mqtt-and-ftp)
   - [What this fork fixes](#what-this-fork-fixes)
@@ -106,7 +147,6 @@ See the [changelog](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main
   - [Slicing Tools](#slicing-tools)
   - [Advanced Tools](#advanced-tools)
 - [Available Resources](#available-resources)
-- [Example Commands for Claude](#example-commands-for-claude)
 - [Bambu Lab Printer Limitations](#bambu-lab-printer-limitations)
 - [General Limitations and Considerations](#general-limitations-and-considerations)
   - [Memory usage](#memory-usage)
@@ -154,7 +194,7 @@ 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.
 - 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
@@ -164,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
@@ -752,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"
@@ -872,11 +918,11 @@ 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.
 
 #### 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
 
@@ -1165,62 +1211,6 @@ Resources follow the MCP resource protocol and can be read by calling `ReadResou
 
 </details>
 
-<details>
-<summary><strong>Example Commands for Claude</strong></summary>
-
-## Example Commands for Claude
-
-After connecting the MCP server in Claude Desktop or Claude Code, you can ask Claude to perform these operations directly in conversation.
-
-### Printer status and control
-
-- "What is the current status of my Bambu printer?"
-- "What temperature is the bed at right now?"
-- "Show me the files on my printer's SD card."
-- "Cancel the current print job."
-- "Set the nozzle temperature to 220 degrees."
-- "Set the bed to 65 degrees."
-- "Turn the chamber light on."
-- "Set the chamber fan to 40 percent."
-- "List the object IDs in this sliced 3MF."
-- "Skip object 6495 on the current print."
-- "Start the AMS drying cycle on AMS 0."
-- "Stop drying on AMS 1."
-- "Match the AMS slots for this 3MF against my loaded filaments without printing."
-- "Auto-match AMS slots and print this 3MF."
-- "Take a camera snapshot of the print bed."
-- "Show me the HMS error codes on the printer."
-- "What speed mode is the printer in?"
-- "Set the airduct to cooling mode."
-
-### Printing 3MF files
-
-- "Print the file at ~/Downloads/bracket.3mf on my Bambu printer."
-- "Upload bracket.3mf to the printer and start printing with AMS slots 0 and 1."
-- "Print my_model.3mf with bed leveling enabled and vibration calibration off."
-- "Upload this 3MF without printing it yet."
-- "Use FULU OrcaSlicer-bambulab to prepare this model, then show me the sliced output before printing."
-- "Probe the FULU BambuNetwork bridge without starting a print."
-
-### STL manipulation
-
-- "What are the dimensions of this STL file?"
-- "Scale model.stl to twice its current size."
-- "Scale this model so it is 150% as wide but stays the same height."
-- "Rotate this STL 90 degrees around the Z axis."
-- "Extend the base of this model by 3mm so it sticks to the bed better."
-- "Center this model at the origin."
-- "Orient this model so its largest flat face is on the bottom."
-- "Merge any near-duplicate vertices in this STL to clean it up."
-
-### Combined workflows
-
-- "Rotate model.stl 45 degrees around Z, extend the base by 2mm, then print it on my Bambu P1S."
-- "Take this unsliced 3MF, slice it with BambuStudio, and print the result."
-- "Scale this part to 80% of its size, lay it flat, and start a print."
-
-</details>
-
 <details>
 <summary><strong>Bambu Lab Printer Limitations</strong></summary>
 

package/dist/bambu-network-bridge.d.ts

@@ -5,6 +5,10 @@ export type BambuNetworkBridgeOptions = {
     countryCode?: string;
     userInfo?: string;
     timeoutMs?: number;
+    /** Trusted in-process preflight; never populated from tool arguments. */
+    beforeDispatch?: (method: string) => Promise<void>;
+    assertDispatchAllowed?: (method: string) => void;
+    onDispatched?: (method: string) => void;
 };
 export type BambuNetworkBridgeStatus = {
     configured: boolean;

package/dist/bambu-network-bridge.js

@@ -161,6 +161,7 @@ export class BambuNetworkBridge {
             throw new Error("BambuNetwork bridge method is required.");
         }
         await this.ensureStarted(options.bridgeCommand);
+        await options.beforeDispatch?.(method);
         const id = this.nextRequestId++;
         const requestPayload = Buffer.from(JSON.stringify({ method, payload }), "utf8");
         const frame = Buffer.alloc(FRAME_HEADER_SIZE + requestPayload.length);
@@ -176,6 +177,7 @@ export class BambuNetworkBridge {
             }, options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
             this.pending.set(id, { method, resolve, reject, timer });
             try {
+                options.assertDispatchAllowed?.(method);
                 this.child.stdin.write(frame, (error) => {
                     if (error) {
                         const pending = this.pending.get(id);
@@ -186,6 +188,7 @@ export class BambuNetworkBridge {
                         }
                     }
                 });
+                options.onDispatched?.(method);
             }
             catch (error) {
                 clearTimeout(timer);