mcp-3d-printer-server 1.2.30 → 1.2.31

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.2.31] – 2026-11-04
+
+### Added
+
+- A printer refusal on `print_3mf` carries a stable `code` in its structured error: `printer-command-rejected` when the printer refuses the print command itself (Bambu HMS 0500-0500-0001-0007, MQTT command verification; the file is on the printer, nothing is printing), and `printer-not-ready` when the printer isn't in a state that can start a print. The message and suggestion are unchanged. Clients such as Counterpart can act on the code instead of matching the wording, which changes with printers and firmware. Checked with mocked MQTT only. Same change as bambu-printer-mcp 1.1.57.
+
 ## [1.2.30] – 2026-11-04
 
 ### Added

package/README.md

@@ -210,6 +210,7 @@ The optional FULU **BambuNetwork bridge** is a separate runtime. With `BAMBU_DEF
 - Per-call `type`, `host`, `port`, and `api_key` arguments for working with more than one printer
 - Printer status, file listing, G-code upload from inline content or a local path, starting a stored file, pausing, resuming, cancelling a job, and setting bed or nozzle temperatures
 - The `counterpart/1` tools shared with [bambu-printer-mcp](https://github.com/DMontgomery40/bambu-printer-mcp): one progress shape for every firmware (state, job, progress, time left, layers, temperatures, problems), detected printer capabilities, camera snapshots, and the loaded filament (Spoolman on Moonraker)
+- Errors carry their details in `structuredContent` (`status`, `retryable`, `suggestion`, `message`); a printer refusal on `print_3mf` also carries a stable `code`, `printer-command-rejected` or `printer-not-ready`, so a client can act on the code instead of the wording.
 - STL tools: inspect dimensions, scale, rotate, translate, extend the base, merge vertices, center, lay flat, transform one section of a model, and render multi-angle SVG previews
 - A print and heating safety gate on every backend: the exact G-code is inspected, every heater target is checked against hardware and material ceilings, and the printer's state is checked. There is no confirmation prompt and no bed check: your client's own print action is the approval. Heater-off, pause, and cancel are never gated; resume only continues a paused job this server inspected and started, and asks a person only when the printer cannot hand the file back for re-reading
 - Slicing through PrusaSlicer, Slic3r, OrcaSlicer, CuraEngine, FULU OrcaSlicer-bambulab, or Bambu Studio command lines, with G-code peak-temperature checks and a one-call process-and-print pipeline

package/dist/index.js

@@ -20,6 +20,7 @@ import { PrinterFactory } from "./printers/printer-factory.js";
 import { STLManipulator, SUPPORT_TYPES } from "./stl/stl-manipulator.js";
 import { parsePauseLayers, readPlateGcode, pausedLayers, machinePauseGcode } from "./slicer/layer-pauses.js";
 import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
+import { PrinterRefusal } from "./refusal.js";
 import { CounterpartService } from "./counterpart/service.js";
 import { CAMERA_STREAM_TOOLS } from "./counterpart/camera-tools.js";
 import { annotateTools } from "./tool-annotations.js";
@@ -2817,7 +2818,9 @@ class ThreeDPrinterMCPServer {
                         }
                         catch (printError) {
                             console.error(`Error starting 3MF print for ${threeMfFilename}:`, printError);
-                            throw new Error(`Failed to start print: ${printError.message}`);
+                            const wrapped = `Failed to start print: ${printError.message}`;
+                            // A printer refusal keeps its code through the wrap: clients act on it (src/refusal.ts).
+                            throw printError instanceof PrinterRefusal ? new PrinterRefusal(printError.code, wrapped) : new Error(wrapped);
                         }
                         break;
                     }
@@ -2910,7 +2913,8 @@ class ThreeDPrinterMCPServer {
             catch (error) {
                 console.error(`Error calling tool ${name}:`, error);
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                const structuredError = this.toStructuredToolError(name, errorMessage, error);
+                // A printer refusal adds its stable code (src/refusal.ts); the message and suggestion stay as they were.
+                const structuredError = { ...this.toStructuredToolError(name, errorMessage, error), ...(error instanceof PrinterRefusal ? { code: error.code } : {}) };
                 return {
                     content: [
                         {

package/dist/printers/bambu.js

@@ -1,3 +1,4 @@
+import { PrinterRefusal } from "../refusal.js";
 import { PrinterImplementation } from "../types.js";
 import { createHash } from "node:crypto";
 import { createReadStream, readFileSync, mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
@@ -671,7 +672,7 @@ export class BambuImplementation extends PrinterImplementation {
                     catch { /* stays unconfirmed */ }
                 }
                 if (verdict === "rejected")
-                    throw new Error(COMMAND_REJECTED_MESSAGE);
+                    throw new PrinterRefusal("printer-command-rejected", COMMAND_REJECTED_MESSAGE);
                 stillActive();
                 return verdict ?? "unconfirmed";
             },

package/dist/refusal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A printer refusal with a stable code, returned as structuredContent.code on the tool's error, so clients
+ * such as Counterpart act on the code instead of matching the message (whose words, HMS numbers and
+ * firmware details change with the printer). Neither one starts a print.
+ *
+ * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
+ *   MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
+ * - printer-not-ready: the printer isn't in a state that can start a print (busy, paused, failed, unknown).
+ */
+export declare const REFUSAL_CODES: readonly ["printer-command-rejected", "printer-not-ready"];
+export type RefusalCode = (typeof REFUSAL_CODES)[number];
+export declare class PrinterRefusal extends Error {
+    readonly code: RefusalCode;
+    constructor(code: RefusalCode, message: string);
+}

package/dist/refusal.js

@@ -0,0 +1,17 @@
+/**
+ * A printer refusal with a stable code, returned as structuredContent.code on the tool's error, so clients
+ * such as Counterpart act on the code instead of matching the message (whose words, HMS numbers and
+ * firmware details change with the printer). Neither one starts a print.
+ *
+ * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
+ *   MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
+ * - printer-not-ready: the printer isn't in a state that can start a print (busy, paused, failed, unknown).
+ */
+export const REFUSAL_CODES = ["printer-command-rejected", "printer-not-ready"];
+export class PrinterRefusal extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PrinterRefusal";
+    }
+}

package/dist/safety/printer-state.js

@@ -1,3 +1,4 @@
+import { PrinterRefusal } from "../refusal.js";
 import { HIDDEN_HMS } from "./hidden-hms.js";
 import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
 const MAX_REPORT_AGE_MS = 15000;
@@ -332,7 +333,7 @@ function validateErrors(raw, requireIdle, serial, model) {
     const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
     const terminal = isCancelledX2DJob(raw, model) || isFinishedP1SJob(raw, model);
     if (requireIdle && !["IDLE", "FINISH"].includes(state) && !terminal)
-        throw new Error(`Printer state ${state} is not safely idle.`);
+        throw new PrinterRefusal("printer-not-ready", `Printer state ${state} is not safely idle.`);
     if (!requireIdle && !["IDLE", "FINISH", "RUNNING", "PAUSE"].includes(state) && !terminal)
         throw new Error(`Printer state ${state} is unknown or failed.`);
     if (finiteNumber(raw.print_error) !== 0 && !isPauseNotice(raw, requireIdle))

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mcp-3d-printer-server",
     "mcpName": "io.github.DMontgomery40/mcp-3d-printer-server",
-    "version": "1.2.30",
+    "version": "1.2.31",
     "description": "MCP server for connecting Claude with 3D printer management systems",
     "main": "dist/index.js",
     "repository": "https://github.com/DMontgomery40/mcp-3D-printer-server",
@@ -32,6 +32,8 @@
         "dist/http-server.js",
         "dist/index.d.ts",
         "dist/index.js",
+        "dist/refusal.d.ts",
+        "dist/refusal.js",
         "dist/printers",
         "dist/safety",
         "dist/sse-server.d.ts",

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/DMontgomery40/mcp-3D-printer-server",
     "source": "github"
   },
-  "version": "1.2.30",
+  "version": "1.2.31",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mcp-3d-printer-server",
-      "version": "1.2.30",
+      "version": "1.2.31",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/src/index.ts

@@ -37,6 +37,7 @@ import { PrinterFactory } from "./printers/printer-factory.js";
 import { STLManipulator, SUPPORT_TYPES, type BambuSliceOptions, type ProcessOverrides, type SliceOutput } from "./stl/stl-manipulator.js";
 import { parsePauseLayers, readPlateGcode, pausedLayers, machinePauseGcode } from "./slicer/layer-pauses.js";
 import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
+import { PrinterRefusal } from "./refusal.js";
 import { CounterpartService, type BambuControlRoute, type PrinterTarget } from "./counterpart/service.js";
 import {CAMERA_STREAM_TOOLS} from "./counterpart/camera-tools.js";
 import { annotateTools } from "./tool-annotations.js";
@@ -736,6 +737,8 @@ type StructuredToolError = {
   suggestion: string;
   message: string;
   tool: string;
+  /** A stable refusal code (src/refusal.ts) when the printer refused; clients act on it, not on the words. */
+  code?: string;
   slicer?: Record<string, unknown>;
   /** The slicer's own result.json, verbatim. */
   slicer_result?: Record<string, unknown>;
@@ -3185,7 +3188,9 @@ class ThreeDPrinterMCPServer {
                 // Report what the printer did, not merely that a command was published.
             } catch (printError) {
                  console.error(`Error starting 3MF print for ${threeMfFilename}:`, printError);
-                 throw new Error(`Failed to start print: ${(printError as Error).message}`);
+                 const wrapped = `Failed to start print: ${(printError as Error).message}`;
+                 // A printer refusal keeps its code through the wrap: clients act on it (src/refusal.ts).
+                 throw printError instanceof PrinterRefusal ? new PrinterRefusal(printError.code, wrapped) : new Error(wrapped);
             }
 
             break;
@@ -3342,7 +3347,8 @@ class ThreeDPrinterMCPServer {
         console.error(`Error calling tool ${name}:`, error);
         
         const errorMessage = error instanceof Error ? error.message : String(error);
-        const structuredError = this.toStructuredToolError(name, errorMessage, error);
+        // A printer refusal adds its stable code (src/refusal.ts); the message and suggestion stay as they were.
+        const structuredError = { ...this.toStructuredToolError(name, errorMessage, error), ...(error instanceof PrinterRefusal ? { code: error.code } : {}) };
         
         return {
           content: [

package/src/printers/bambu.ts

@@ -1,3 +1,4 @@
+import { PrinterRefusal } from "../refusal.js";
 import { PrinterImplementation } from "../types.js";
 import { createHash } from "node:crypto";
 import { createReadStream, readFileSync, mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
@@ -782,7 +783,7 @@ export class BambuImplementation extends PrinterImplementation {
         if (verdict === undefined) {
           try { verdict = judge((await this.getSafetyStatus(host, serial, token))?.raw); } catch { /* stays unconfirmed */ }
         }
-        if (verdict === "rejected") throw new Error(COMMAND_REJECTED_MESSAGE);
+        if (verdict === "rejected") throw new PrinterRefusal("printer-command-rejected", COMMAND_REJECTED_MESSAGE);
         stillActive();
         return verdict ?? "unconfirmed";
       },

package/src/safety/printer-state.ts

@@ -1,3 +1,4 @@
+import { PrinterRefusal } from "../refusal.js";
 import { HIDDEN_HMS } from "./hidden-hms.js";
 import type { BambuClient } from "bambu-node";
 import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
@@ -341,7 +342,7 @@ export function isPauseNotice(raw: Record<string, any>, requireIdle: boolean): b
 function validateErrors(raw: Record<string,any>, requireIdle: boolean, serial: string, model: string) {
   const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
   const terminal = isCancelledX2DJob(raw, model) || isFinishedP1SJob(raw, model);
-  if (requireIdle && !["IDLE","FINISH"].includes(state) && !terminal) throw new Error(`Printer state ${state} is not safely idle.`);
+  if (requireIdle && !["IDLE","FINISH"].includes(state) && !terminal) throw new PrinterRefusal("printer-not-ready", `Printer state ${state} is not safely idle.`);
   if (!requireIdle && !["IDLE","FINISH","RUNNING","PAUSE"].includes(state) && !terminal) throw new Error(`Printer state ${state} is unknown or failed.`);
   if (finiteNumber(raw.print_error) !== 0 && !isPauseNotice(raw, requireIdle)) throw new Error("Printer reports a print error or did not report its error state.");
   if (!Array.isArray(raw.hms)) throw new Error("Printer HMS error state is missing or malformed.");