bambu-printer-mcp 1.1.56 → 1.1.57

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1075,7 +1075,7 @@ If the project does not match those assumptions, the tool fails fast with a stru
1075
1075
 
1076
1076
  #### Counterpart tools (`counterpart/1`)
1077
1077
 
1078
- [Counterpart](https://github.com/DMontgomery40/scan-to-make) (Scan to Make) reads printers through a small contract that this server and [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) share. Each tool declares an `outputSchema` and returns `structuredContent`, plus the same JSON as text for older clients. An error is returned as text only, because MCP clients check `structuredContent` against the schema even on errors. `counterpart_printer_info` and `counterpart_print_progress` take the usual optional `host`, `bambu_serial`, `bambu_token` and `bambu_model` (default `BAMBU_MODEL`) arguments.
1078
+ [Counterpart](https://github.com/DMontgomery40/scan-to-make) (Scan to Make) reads printers through a small contract that this server and [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) share. Each tool declares an `outputSchema` and returns `structuredContent`, plus the same JSON as text for older clients. An error is returned as text only, because MCP clients check `structuredContent` against the schema even on errors. Other tools return an error's details in `structuredContent` (`status`, `retryable`, `suggestion`, `message`). When the printer refuses a print, it also carries a stable `code`, either `printer-command-rejected` or `printer-not-ready`, so a client can act on the code rather than the wording. `counterpart_printer_info` and `counterpart_print_progress` take the usual optional `host`, `bambu_serial`, `bambu_token` and `bambu_model` (default `BAMBU_MODEL`) arguments.
1079
1079
 
1080
1080
  - **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, serial, host}, capabilities}`. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `cameraStream: true` for supported camera models, `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
1081
1081
  - **`counterpart_print_route`** reads or changes how prints and Stop/Pause/Resume reach the printer: `{route, mode, type, choices, savedTo}`, where `route` is `lan` (the local network, in the configured `BAMBU_DEFAULT_CONNECTION_MODE`) or `cloud` (Bambu Cloud through the [FULU bridge](docs/FULU.md)). Pass `route` to change it; the next print and control use it at once, and it is written to the `.env` in the server's working directory when one exists (`savedTo`, otherwise `null`). It is not part of the shared contract: it has no `outputSchema`, and mcp-3D-printer-server has no Bambu Cloud route.
package/dist/index.js CHANGED
@@ -34,6 +34,7 @@ import { makeCounterpart3mf } from "./counterpart/make-3mf.js";
34
34
  import { MAKE_3MF_OUTPUT_SCHEMA, PRINT_PROGRESS_OUTPUT_SCHEMA, PRINTER_INFO_OUTPUT_SCHEMA } from "./counterpart/schemas.js";
35
35
  import { parseProcessOverrides } from "./slicer/process-overrides.js";
36
36
  import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
37
+ import { PrinterRefusal } from "./refusal.js";
37
38
  import { machinePauseGcode, parsePauseLayers, pausedLayers, readPlateGcode } from "./slicer/layer-pauses.js";
38
39
  dotenv.config();
39
40
  const DEFAULT_HOST = process.env.BAMBU_PRINTER_HOST || process.env.PRINTER_HOST || "localhost";
@@ -4098,6 +4099,7 @@ class BambuPrinterMCPServer {
4098
4099
  : `Check parameters and try again. Error: ${message}`,
4099
4100
  message,
4100
4101
  tool: name,
4102
+ ...(error instanceof PrinterRefusal ? { code: error.code } : {}),
4101
4103
  // The slicer's own result.json; the message starts with its error_string and warnings.
4102
4104
  ...(error instanceof SlicerRunError && error.slicerResult ? { slicer_result: error.slicerResult } : {}),
4103
4105
  };
@@ -1,3 +1,4 @@
1
+ import { PrinterRefusal } from "../refusal.js";
1
2
  import { CameraStreams } from "./camera-stream.js";
2
3
  import { openTcpCameraSource, openRtspCameraSource } from "./camera-sources.js";
3
4
  import { cameraNumber } from "./camera-tools.js";
@@ -1881,7 +1882,7 @@ export class BambuImplementation {
1881
1882
  if (verdict === "rejected") {
1882
1883
  // Nothing started, so there is no checked job to resume or clear later.
1883
1884
  this.checkedJobs.delete(`${host}\n${serial}`);
1884
- throw new Error(COMMAND_REJECTED_MESSAGE);
1885
+ throw new PrinterRefusal("printer-command-rejected", COMMAND_REJECTED_MESSAGE);
1885
1886
  }
1886
1887
  if (verdict === "cancelled" || cancelled())
1887
1888
  throw new Error(DISPATCH_CANCELLED_MESSAGE);
@@ -0,0 +1,15 @@
1
+ /**
2
+ * A printer refusal with a stable code, returned as structuredContent.code on the tool's error, so clients
3
+ * such as Counterpart act on the code instead of matching the message (whose words, HMS numbers and
4
+ * firmware details change with the printer). Neither one starts a print.
5
+ *
6
+ * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
7
+ * MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
8
+ * - printer-not-ready: the printer isn't in a state that can start a print (busy, paused, failed, unknown).
9
+ */
10
+ export declare const REFUSAL_CODES: readonly ["printer-command-rejected", "printer-not-ready"];
11
+ export type RefusalCode = (typeof REFUSAL_CODES)[number];
12
+ export declare class PrinterRefusal extends Error {
13
+ readonly code: RefusalCode;
14
+ constructor(code: RefusalCode, message: string);
15
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * A printer refusal with a stable code, returned as structuredContent.code on the tool's error, so clients
3
+ * such as Counterpart act on the code instead of matching the message (whose words, HMS numbers and
4
+ * firmware details change with the printer). Neither one starts a print.
5
+ *
6
+ * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
7
+ * MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
8
+ * - printer-not-ready: the printer isn't in a state that can start a print (busy, paused, failed, unknown).
9
+ */
10
+ export const REFUSAL_CODES = ["printer-command-rejected", "printer-not-ready"];
11
+ export class PrinterRefusal extends Error {
12
+ constructor(code, message) {
13
+ super(message);
14
+ this.code = code;
15
+ this.name = "PrinterRefusal";
16
+ }
17
+ }
@@ -1,3 +1,4 @@
1
+ import { PrinterRefusal } from "../refusal.js";
1
2
  import { HIDDEN_HMS } from "./hidden-hms.js";
2
3
  import { GetVersionCommand, PushAllCommand } from "bambu-node";
3
4
  import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
@@ -330,7 +331,7 @@ function validateErrors(raw, requireIdle, serial, model) {
330
331
  const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
331
332
  const terminal = isCancelledX2DJob(raw, model) || isFinishedP1SJob(raw, model);
332
333
  if (requireIdle && !["IDLE", "FINISH"].includes(state) && !terminal)
333
- throw new Error(`Printer state ${state} is not safely idle.`);
334
+ throw new PrinterRefusal("printer-not-ready", `Printer state ${state} is not safely idle.`);
334
335
  if (!requireIdle && !["IDLE", "FINISH", "RUNNING", "PAUSE"].includes(state) && !terminal)
335
336
  throw new Error(`Printer state ${state} is unknown or failed.`);
336
337
  if (finiteNumber(raw.print_error) !== 0 && !isPauseNotice(raw, requireIdle))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bambu-printer-mcp",
3
- "version": "1.1.56",
3
+ "version": "1.1.57",
4
4
  "description": "MCP server for Bambu Lab 3D printers with STL manipulation, slicing, and print management",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
package/src/index.ts CHANGED
@@ -64,6 +64,7 @@ import { makeCounterpart3mf } from "./counterpart/make-3mf.js";
64
64
  import { MAKE_3MF_OUTPUT_SCHEMA, PRINT_PROGRESS_OUTPUT_SCHEMA, PRINTER_INFO_OUTPUT_SCHEMA } from "./counterpart/schemas.js";
65
65
  import { parseProcessOverrides } from "./slicer/process-overrides.js";
66
66
  import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
67
+ import { PrinterRefusal } from "./refusal.js";
67
68
  import { machinePauseGcode, parsePauseLayers, pausedLayers, readPlateGcode } from "./slicer/layer-pauses.js";
68
69
 
69
70
  dotenv.config();
@@ -964,6 +965,8 @@ type StructuredToolError = {
964
965
  suggestion: string;
965
966
  message: string;
966
967
  tool: string;
968
+ /** A stable refusal code (src/refusal.ts) when the printer refused; clients act on it, not on the words. */
969
+ code?: string;
967
970
  slicer_result?: Record<string, unknown>;
968
971
  };
969
972
 
@@ -4855,6 +4858,7 @@ class BambuPrinterMCPServer {
4855
4858
  : `Check parameters and try again. Error: ${message}`,
4856
4859
  message,
4857
4860
  tool: name,
4861
+ ...(error instanceof PrinterRefusal ? { code: error.code } : {}),
4858
4862
  // The slicer's own result.json; the message starts with its error_string and warnings.
4859
4863
  ...(error instanceof SlicerRunError && error.slicerResult ? { slicer_result: error.slicerResult } : {}),
4860
4864
  };
@@ -1,3 +1,4 @@
1
+ import { PrinterRefusal } from "../refusal.js";
1
2
  import {CameraStreams, type FrameOptions} from "./camera-stream.js";
2
3
  import {openTcpCameraSource, openRtspCameraSource} from "./camera-sources.js";
3
4
  import {cameraNumber} from "./camera-tools.js";
@@ -2069,7 +2070,7 @@ export class BambuImplementation {
2069
2070
  if (verdict === "rejected") {
2070
2071
  // Nothing started, so there is no checked job to resume or clear later.
2071
2072
  this.checkedJobs.delete(`${host}\n${serial}`);
2072
- throw new Error(COMMAND_REJECTED_MESSAGE);
2073
+ throw new PrinterRefusal("printer-command-rejected", COMMAND_REJECTED_MESSAGE);
2073
2074
  }
2074
2075
  if (verdict === "cancelled" || cancelled()) throw new Error(DISPATCH_CANCELLED_MESSAGE);
2075
2076
  return verdict ?? "unconfirmed";
package/src/refusal.ts ADDED
@@ -0,0 +1,18 @@
1
+ /**
2
+ * A printer refusal with a stable code, returned as structuredContent.code on the tool's error, so clients
3
+ * such as Counterpart act on the code instead of matching the message (whose words, HMS numbers and
4
+ * firmware details change with the printer). Neither one starts a print.
5
+ *
6
+ * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
7
+ * MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
8
+ * - printer-not-ready: the printer isn't in a state that can start a print (busy, paused, failed, unknown).
9
+ */
10
+ export const REFUSAL_CODES = ["printer-command-rejected", "printer-not-ready"] as const;
11
+ export type RefusalCode = (typeof REFUSAL_CODES)[number];
12
+
13
+ export class PrinterRefusal extends Error {
14
+ constructor(readonly code: RefusalCode, message: string) {
15
+ super(message);
16
+ this.name = "PrinterRefusal";
17
+ }
18
+ }
@@ -1,3 +1,4 @@
1
+ import { PrinterRefusal } from "../refusal.js";
1
2
  import { HIDDEN_HMS } from "./hidden-hms.js";
2
3
  import { BambuClient, GetVersionCommand, PushAllCommand } from "bambu-node";
3
4
  import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
@@ -338,7 +339,7 @@ export function isPauseNotice(raw: Record<string, any>, requireIdle: boolean): b
338
339
  function validateErrors(raw: Record<string,any>, requireIdle: boolean, serial: string, model: string) {
339
340
  const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
340
341
  const terminal = isCancelledX2DJob(raw, model) || isFinishedP1SJob(raw, model);
341
- if (requireIdle && !["IDLE","FINISH"].includes(state) && !terminal) throw new Error(`Printer state ${state} is not safely idle.`);
342
+ if (requireIdle && !["IDLE","FINISH"].includes(state) && !terminal) throw new PrinterRefusal("printer-not-ready", `Printer state ${state} is not safely idle.`);
342
343
  if (!requireIdle && !["IDLE","FINISH","RUNNING","PAUSE"].includes(state) && !terminal) throw new Error(`Printer state ${state} is unknown or failed.`);
343
344
  if (finiteNumber(raw.print_error) !== 0 && !isPauseNotice(raw, requireIdle)) throw new Error("Printer reports a print error or did not report its error state.");
344
345
  if (!Array.isArray(raw.hms)) throw new Error("Printer HMS error state is missing or malformed.");