bambu-printer-mcp 1.1.80 → 1.1.82

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
@@ -1097,7 +1097,7 @@ If the project does not match those assumptions, the tool fails fast with a stru
1097
1097
  - `activeFilament`: the loaded spool's `material` and `#RRGGBB` `color`. `slot` is the index `ams_slots` uses: `amsId × 4 + tray` for an AMS, the unit id (128 and up) for an AMS-HT, and `"ext"` for the external spool, or `"254"` (left) / `"255"` (right) on dual-nozzle H2D, H2C and X2D. On H2 and X2D it comes from the active extruder's report.
1098
1098
  - `problems`: a non-zero `print_error` as 8 hex digits, such as `07008011`, and each HMS entry as `AAAA_BBBB_CCCC_DDDD`, such as `0300_1800_0001_0003`. Severity follows Bambu's HMS level: fatal is `fatal`, serious `error`, common `warning` and info `info`. Each HMS problem links to Bambu's page for that code. Messages come from the English HMS tables bundled with the pinned Bambu Studio release; `scripts/generate-hms-messages.mjs` turns them into `src/safety/hms-messages.ts` and the stage words into `src/printers/bambu-stages.ts`. A model without its own table, such as the P1S, gets the text the other tables share. A code none of them has falls back to the user's own Bambu Studio download: `hms_en_<serial prefix>.json`, then `hms_en.json`, in the `hms` folder next to `BambuStudio.conf` (see `BAMBU_STUDIO_CONFIG`). Those files are read only, and Bambu's text is passed through unchanged. Codes that Bambu lists for a printer without text are reported as `info`.
1099
1099
  - **`counterpart_discover_printers`** listens for Bambu printers' own SSDP announcements on UDP 2021 for `duration_ms` (default 4000, 500–15000) and sends one M-SEARCH: `{contract, network, printers: [{kind: "bambu", source: "ssdp", name, host, serial, model?, firmware?}]}`. `model` is the `bambu_model` value the announced DevModel or the serial prefix names (none for the X1, which `bambu_model` doesn't take). An announcement counts only from a private IPv4 address that names itself as its `Location`. `network` is `unavailable` when another app (Bambu Studio) holds the port. It never connects to or authenticates with a printer.
1100
- - **`counterpart_setup_fields`** says what this server needs to drive a printer, so a client can offer setup without printer tables of its own: `{contract, server, kinds: [{kind: "bambu", label, env, fields}], model?}`. Each field names its form role (`host`, `serial`, `model`, `secret`), the `.env` variable to write (`PRINTER_HOST`, `BAMBU_SERIAL`, `BAMBU_MODEL`, `BAMBU_TOKEN`) and its older `aliases`, which this server reads first (a client writing the variable removes them), a label and hint, and whether it is required. The model field lists the `bambu_model` choices with Bambu's names and `fromSerial`, the model each three-character serial prefix names. Pass `serial` to get that model as `model`. `slicer` reports the slicer this server would run (type, path, whether it is there, and the Bambu profiles folder) with the `SLICER_TYPE`, `SLICER_PATH` (`input: "path"`) and `BAMBU_PROFILES_ROOT` fields, each required only when what it defaults to is missing. It sends nothing to a printer and returns no secret.
1100
+ - **`counterpart_setup_fields`** says what this server needs to drive a printer, so a client can offer setup without printer tables of its own: `{contract, server, kinds: [{kind: "bambu", label, env, cameraSnapshot, fields}], model?}`. `cameraSnapshot: true` says `camera_snapshot` reads the printer's camera with only the settings the fields write, so a client's setup check can ask for a picture as well as the status (RTSP models still need ffmpeg, as `camera_snapshot` always does); every kind declares it. Each field names its form role (`host`, `serial`, `model`, `secret`), the `.env` variable to write (`PRINTER_HOST`, `BAMBU_SERIAL`, `BAMBU_MODEL`, `BAMBU_TOKEN`) and its older `aliases`, which this server reads first (a client writing the variable removes them), a label and hint, and whether it is required. The model field lists the `bambu_model` choices with Bambu's names and `fromSerial`, the model each three-character serial prefix names. Pass `serial` to get that model as `model`. `slicer` reports the slicer this server would run (type, path, whether it is there, and the Bambu profiles folder) with the `SLICER_TYPE`, `SLICER_PATH` (`input: "path"`) and `BAMBU_PROFILES_ROOT` fields, each required only when what it defaults to is missing. It sends nothing to a printer and returns no secret.
1101
1101
  - **`counterpart_propose_filaments`** proposes which loaded AMS spool prints each of a model's colours, before slicing. Pass `filaments` (`index`, `name`, `colour` `#RRGGBB`, `material`), the `painted` slots no part names, `sliced: true` for an already-sliced file and, at print time, the person's `chosen` spools. It reads the live AMS once and returns:
1102
1102
  - `trays`: the spools to choose from, each with `label` (`A2`, as Bambu Studio labels trays), `name` (Bambu Studio's colour name and the product, "Sunflower Yellow PLA Basic", from the configured slicer's `filaments_color_codes.json`), `colour`, `material`, `filamentId`, `feed`, `sliceable` and, when one resolves, `profile` (the filament profile path `slice_stl` takes in `load_filaments`). An unsliced model lists only spools with a filament profile.
1103
1103
  - `proposal`: per filament, the nearest spool in OKLab colour with the asked-for material preferred, and a `verdict`: `same-colour` (within 0.08), `closest` (that colour isn't loaded; `note` says so, "White isn't loaded. Closest loaded: A2 Sunflower Yellow PLA Basic."), `no-colour` or `none`. A sliced file's material is a hard rule. One print feeds from one `feed`.
@@ -1550,3 +1550,7 @@ Thank you to **[FULU Foundation](https://www.fulu.org/), [Louis Rossmann](https:
1550
1550
  Some printer command surfaces and workflow priorities were informed by [Bambuddy](https://github.com/maziggy/bambuddy), an AGPL-3.0 Bambu Lab printer management project. This project does not vendor Bambuddy code.
1551
1551
 
1552
1552
  </details>
1553
+
1554
+ ### Print dispatch truth (`counterpart/1`)
1555
+
1556
+ An error from `print_3mf` or `upload_gcode` carries `structuredContent.printOutcome`: `not-sent` means no print command was handed to a transport (including fresh-report timeouts, preparation failures and upload failures); `unknown` means a command may have reached the printer; `rejected` means the printer refused the command. A file upload alone is not a print command. Clients use this field, never error wording or firmware codes, to distinguish “Not started” from a print that needs checking. Missing or unrecognized values cannot prove nothing was sent. Other structured error fields remain compatible.
@@ -29,6 +29,12 @@ export type SetupKind = {
29
29
  label: string;
30
30
  /** Values this server needs for the kind whatever the person enters (MCP_TRANSPORT, PRINTER_TYPE). */
31
31
  env: Record<string, string>;
32
+ /**
33
+ * Whether camera_snapshot reads this kind's camera with only the settings these fields write, so a client's setup
34
+ * check can ask for a picture as well as the status. What else the computer needs (ffmpeg for RTSP models) is
35
+ * reported in camera_snapshot's own error. Every kind declares it; a client reads it missing as an older server.
36
+ */
37
+ cameraSnapshot: boolean;
32
38
  fields: SetupField[];
33
39
  };
34
40
  /** The slicer this server runs, as it resolves it now, and the settings that choose it (for every printer). */
@@ -119,6 +125,10 @@ export declare const SETUP_FIELDS_OUTPUT_SCHEMA: {
119
125
  type: string;
120
126
  };
121
127
  };
128
+ cameraSnapshot: {
129
+ type: string;
130
+ description: string;
131
+ };
122
132
  fields: {
123
133
  type: string;
124
134
  items: {
@@ -51,6 +51,8 @@ export function bambuSetupFields(options) {
51
51
  server: options.server,
52
52
  kinds: [{
53
53
  kind: "bambu", label: "Bambu Lab", env: { MCP_TRANSPORT: "stdio" },
54
+ // Every offered model has a built-in camera; the model field chooses its transport (camera-models.ts).
55
+ cameraSnapshot: true,
54
56
  fields: [
55
57
  { name: "host", env: "PRINTER_HOST", aliases: ["BAMBU_PRINTER_HOST"], label: "Address", hint: "The printer's IP address: on the printer, Settings → WLAN", required: true },
56
58
  { name: "serial", env: "BAMBU_SERIAL", aliases: ["BAMBU_PRINTER_SERIAL"], label: "Serial number", hint: "On the printer: Settings → Device", required: true, transform: "uppercase" },
@@ -79,8 +81,10 @@ export const SETUP_FIELDS_OUTPUT_SCHEMA = {
79
81
  server: { type: "object", properties: { name: { type: "string" }, version: { type: "string" } }, required: ["name", "version"] },
80
82
  kinds: { type: "array", items: { type: "object", properties: {
81
83
  kind: { type: "string", enum: [...PRINTER_KINDS] }, label: { type: "string" },
82
- env: { type: "object", additionalProperties: { type: "string" } }, fields: { type: "array", items: field },
83
- }, required: ["kind", "label", "env", "fields"] } },
84
+ env: { type: "object", additionalProperties: { type: "string" } },
85
+ cameraSnapshot: { type: "boolean", description: "Whether camera_snapshot reads this kind's camera with only the settings these fields write, so a setup check can ask for a picture too." },
86
+ fields: { type: "array", items: field },
87
+ }, required: ["kind", "label", "env", "cameraSnapshot", "fields"] } },
84
88
  model: { type: "string" },
85
89
  slicer: { type: "object", properties: {
86
90
  type: { type: "string" }, path: { type: "string" }, found: { type: "boolean" }, profilesRoot: { type: "string" }, profilesFound: { type: "boolean" },
package/dist/index.js CHANGED
@@ -51,7 +51,7 @@ import { makeCounterpart3mf } from "./counterpart/make-3mf.js";
51
51
  import { MAKE_3MF_OUTPUT_SCHEMA, PRINT_PROGRESS_OUTPUT_SCHEMA, PRINTER_INFO_OUTPUT_SCHEMA } from "./counterpart/schemas.js";
52
52
  import { parseProcessOverrides } from "./slicer/process-overrides.js";
53
53
  import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
54
- import { PrinterRefusal } from "./refusal.js";
54
+ import { PrinterRefusal, withPrintDispatch, markPrintCommandSent, printOutcome } from "./refusal.js";
55
55
  import { uploadProgressReporter } from "./upload-progress.js";
56
56
  import { machinePauseGcode, parsePauseLayers, pausedLayers, readPlateGcode } from "./slicer/layer-pauses.js";
57
57
  dotenv.config();
@@ -1551,6 +1551,7 @@ class BambuPrinterMCPServer {
1551
1551
  throw new Error("The printer's SD card or USB stick is no longer ready. Check it and start the print again.");
1552
1552
  }
1553
1553
  assertActive();
1554
+ markPrintCommandSent();
1554
1555
  } });
1555
1556
  assertActive();
1556
1557
  this.bambu.recordCheckedJob(devIp, devId, remoteFileName, requirements, resumeFile, false);
@@ -1566,8 +1567,10 @@ class BambuPrinterMCPServer {
1566
1567
  validatePrinterState(dispatchStatus, requirements);
1567
1568
  this.bambu.assertPrintPreflight(dispatchStatus, preflight);
1568
1569
  },
1569
- assertDispatchAllowed: method => { if (method === bridgeMethod || method === cloudFallbackMethod)
1570
- assertActive(); },
1570
+ assertDispatchAllowed: method => { if (method === bridgeMethod || method === cloudFallbackMethod) {
1571
+ assertActive();
1572
+ markPrintCommandSent();
1573
+ } },
1571
1574
  onDispatched: method => { if (method === bridgeMethod || method === cloudFallbackMethod)
1572
1575
  retainForDispatchedUpload(); },
1573
1576
  };
@@ -3034,7 +3037,7 @@ class BambuPrinterMCPServer {
3034
3037
  },
3035
3038
  {
3036
3039
  name: "counterpart_setup_fields",
3037
- description: "Counterpart contract (counterpart/1): the printers this server drives and the settings it reads for each, by .env variable name (first canonical, then aliases): label, hint, whether required, the model choices and the model each serial-number prefix names. Pass serial to get the model it names. Sends nothing to a printer and returns no configured values.",
3040
+ description: "Counterpart contract (counterpart/1): the printers this server drives and the settings it reads for each, by .env variable name (first canonical, then aliases): label, hint, whether required, the model choices and the model each serial-number prefix names, and whether camera_snapshot reads the printer's camera with only those settings (cameraSnapshot). Pass serial to get the model it names. Sends nothing to a printer and returns no configured values.",
3038
3041
  inputSchema: {
3039
3042
  type: "object",
3040
3043
  properties: { serial: { type: "string", maxLength: 64, description: "A Bambu serial number: model is the one it names, when known." } },
@@ -3197,7 +3200,7 @@ class BambuPrinterMCPServer {
3197
3200
  };
3198
3201
  });
3199
3202
  // A designer's settings extracted for this call are removed when it settles.
3200
- this.server.setRequestHandler(CallToolRequestSchema, (request, extra) => withExtractedSettingsCleanup(async () => {
3203
+ this.server.setRequestHandler(CallToolRequestSchema, (request, extra) => withPrintDispatch(() => withExtractedSettingsCleanup(async () => {
3201
3204
  const { name, arguments: args } = request.params;
3202
3205
  const sendNativeCommand = (options, execution = {}) => sendCommandWithBambuNative(options, { signal: extra.signal, ...execution });
3203
3206
  const progressToken = extra._meta?.progressToken;
@@ -4420,7 +4423,7 @@ class BambuPrinterMCPServer {
4420
4423
  : `Check parameters and try again. Error: ${message}`,
4421
4424
  message,
4422
4425
  tool: name,
4423
- ...(error instanceof PrinterRefusal ? { code: error.code } : {}),
4426
+ ...(error instanceof PrinterRefusal ? { code: error.code } : {}), ...(["print_3mf", "upload_gcode"].includes(name) ? { printOutcome: printOutcome(error) } : {}),
4424
4427
  // The slicer's own result.json; the message starts with its error_string and warnings.
4425
4428
  // A slicer failure always carries slicer_report: the plain sentence a person sees, the slicer's words for the log.
4426
4429
  // The report always says failed (a result.json that says success can still leave no output file).
@@ -4438,7 +4441,7 @@ class BambuPrinterMCPServer {
4438
4441
  isError: true,
4439
4442
  };
4440
4443
  }
4441
- }));
4444
+ })));
4442
4445
  }
4443
4446
  async startStdio() {
4444
4447
  const transport = new StdioServerTransport();
@@ -1,4 +1,4 @@
1
- import { PrinterRefusal } from "../refusal.js";
1
+ import { PrinterRefusal, markPrintCommandSent } from "../refusal.js";
2
2
  import { CameraStreams } from "./camera-stream.js";
3
3
  import { openTcpCameraSource, openRtspCameraSource } from "./camera-sources.js";
4
4
  import { cameraNumber } from "./camera-tools.js";
@@ -1106,6 +1106,7 @@ export class BambuImplementation {
1106
1106
  assertActive();
1107
1107
  if (legacyContainer) {
1108
1108
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
1109
+ markPrintCommandSent();
1109
1110
  try {
1110
1111
  await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remoteProjectPath }));
1111
1112
  }
@@ -1192,6 +1193,7 @@ export class BambuImplementation {
1192
1193
  };
1193
1194
  }
1194
1195
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
1196
+ markPrintCommandSent();
1195
1197
  try {
1196
1198
  await printer.publish(projectFileCmd);
1197
1199
  }
@@ -1797,6 +1799,7 @@ export class BambuImplementation {
1797
1799
  const printer = await this.getPrinter(host, serial, token);
1798
1800
  assertActive();
1799
1801
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
1802
+ markPrintCommandSent();
1800
1803
  try {
1801
1804
  await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remotePath }));
1802
1805
  }
package/dist/refusal.d.ts CHANGED
@@ -1,7 +1,7 @@
1
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.
2
+ * A printer refusal with a stable diagnostic code, retained for existing clients.
3
+ * Counterpart uses structuredContent.printOutcome for dispatch truth, never
4
+ * these firmware-specific codes or the message.
5
5
  *
6
6
  * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
7
7
  * MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
@@ -14,3 +14,9 @@ export declare class PrinterRefusal extends Error {
14
14
  readonly code: RefusalCode;
15
15
  constructor(code: RefusalCode, message: string);
16
16
  }
17
+ /** counterpart/1 dispatch-tool errors describe dispatch truth independently of firmware-specific codes. */
18
+ export type PrintOutcome = "not-sent" | "unknown" | "rejected";
19
+ export declare function withPrintDispatch<T>(run: () => T): T;
20
+ /** Call immediately before handing a print command to a transport. An acknowledgement may then be lost. */
21
+ export declare function markPrintCommandSent(): void;
22
+ export declare function printOutcome(error: unknown): PrintOutcome;
package/dist/refusal.js CHANGED
@@ -1,7 +1,8 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
1
2
  /**
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.
3
+ * A printer refusal with a stable diagnostic code, retained for existing clients.
4
+ * Counterpart uses structuredContent.printOutcome for dispatch truth, never
5
+ * these firmware-specific codes or the message.
5
6
  *
6
7
  * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
7
8
  * MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
@@ -16,3 +17,18 @@ export class PrinterRefusal extends Error {
16
17
  this.name = "PrinterRefusal";
17
18
  }
18
19
  }
20
+ const printDispatch = new AsyncLocalStorage();
21
+ export function withPrintDispatch(run) {
22
+ return printDispatch.run({ attempted: false }, run);
23
+ }
24
+ /** Call immediately before handing a print command to a transport. An acknowledgement may then be lost. */
25
+ export function markPrintCommandSent() {
26
+ const dispatch = printDispatch.getStore();
27
+ if (dispatch)
28
+ dispatch.attempted = true;
29
+ }
30
+ export function printOutcome(error) {
31
+ if (error instanceof PrinterRefusal && error.code === "printer-command-rejected")
32
+ return "rejected";
33
+ return printDispatch.getStore()?.attempted === false ? "not-sent" : "unknown";
34
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bambu-printer-mcp",
3
- "version": "1.1.80",
3
+ "version": "1.1.82",
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": {
@@ -28,6 +28,12 @@ export type SetupKind = {
28
28
  kind: typeof PRINTER_KINDS[number]; label: string;
29
29
  /** Values this server needs for the kind whatever the person enters (MCP_TRANSPORT, PRINTER_TYPE). */
30
30
  env: Record<string, string>;
31
+ /**
32
+ * Whether camera_snapshot reads this kind's camera with only the settings these fields write, so a client's setup
33
+ * check can ask for a picture as well as the status. What else the computer needs (ffmpeg for RTSP models) is
34
+ * reported in camera_snapshot's own error. Every kind declares it; a client reads it missing as an older server.
35
+ */
36
+ cameraSnapshot: boolean;
31
37
  fields: SetupField[];
32
38
  };
33
39
  /** The slicer this server runs, as it resolves it now, and the settings that choose it (for every printer). */
@@ -86,6 +92,8 @@ export function bambuSetupFields(options: { server: { name: string; version: str
86
92
  server: options.server,
87
93
  kinds: [{
88
94
  kind: "bambu", label: "Bambu Lab", env: { MCP_TRANSPORT: "stdio" },
95
+ // Every offered model has a built-in camera; the model field chooses its transport (camera-models.ts).
96
+ cameraSnapshot: true,
89
97
  fields: [
90
98
  { name: "host", env: "PRINTER_HOST", aliases: ["BAMBU_PRINTER_HOST"], label: "Address", hint: "The printer's IP address: on the printer, Settings → WLAN", required: true },
91
99
  { name: "serial", env: "BAMBU_SERIAL", aliases: ["BAMBU_PRINTER_SERIAL"], label: "Serial number", hint: "On the printer: Settings → Device", required: true, transform: "uppercase" },
@@ -115,8 +123,10 @@ export const SETUP_FIELDS_OUTPUT_SCHEMA = {
115
123
  server: { type: "object", properties: { name: { type: "string" }, version: { type: "string" } }, required: ["name", "version"] },
116
124
  kinds: { type: "array", items: { type: "object", properties: {
117
125
  kind: { type: "string", enum: [...PRINTER_KINDS] }, label: { type: "string" },
118
- env: { type: "object", additionalProperties: { type: "string" } }, fields: { type: "array", items: field },
119
- }, required: ["kind", "label", "env", "fields"] } },
126
+ env: { type: "object", additionalProperties: { type: "string" } },
127
+ cameraSnapshot: { type: "boolean", description: "Whether camera_snapshot reads this kind's camera with only the settings these fields write, so a setup check can ask for a picture too." },
128
+ fields: { type: "array", items: field },
129
+ }, required: ["kind", "label", "env", "cameraSnapshot", "fields"] } },
120
130
  model: { type: "string" },
121
131
  slicer: { type: "object", properties: {
122
132
  type: { type: "string" }, path: { type: "string" }, found: { type: "boolean" }, profilesRoot: { type: "string" }, profilesFound: { type: "boolean" },
package/src/index.ts CHANGED
@@ -82,7 +82,7 @@ import { makeCounterpart3mf } from "./counterpart/make-3mf.js";
82
82
  import { MAKE_3MF_OUTPUT_SCHEMA, PRINT_PROGRESS_OUTPUT_SCHEMA, PRINTER_INFO_OUTPUT_SCHEMA } from "./counterpart/schemas.js";
83
83
  import { parseProcessOverrides } from "./slicer/process-overrides.js";
84
84
  import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
85
- import { PrinterRefusal } from "./refusal.js";
85
+ import { PrinterRefusal, withPrintDispatch, markPrintCommandSent, printOutcome } from "./refusal.js";
86
86
  import { uploadProgressReporter } from "./upload-progress.js";
87
87
  import { machinePauseGcode, parsePauseLayers, pausedLayers, readPlateGcode } from "./slicer/layer-pauses.js";
88
88
 
@@ -1951,6 +1951,7 @@ class BambuPrinterMCPServer {
1951
1951
  throw new Error("The printer's SD card or USB stick is no longer ready. Check it and start the print again.");
1952
1952
  }
1953
1953
  assertActive();
1954
+ markPrintCommandSent();
1954
1955
  } });
1955
1956
  assertActive();
1956
1957
  this.bambu.recordCheckedJob(devIp, devId, remoteFileName, requirements, resumeFile, false);
@@ -1965,7 +1966,7 @@ class BambuPrinterMCPServer {
1965
1966
  validatePrinterState(dispatchStatus, requirements);
1966
1967
  this.bambu.assertPrintPreflight(dispatchStatus, preflight);
1967
1968
  },
1968
- assertDispatchAllowed: method => { if (method === bridgeMethod || method === cloudFallbackMethod) assertActive(); },
1969
+ assertDispatchAllowed: method => { if (method === bridgeMethod || method === cloudFallbackMethod) { assertActive(); markPrintCommandSent(); } },
1969
1970
  onDispatched: method => { if (method === bridgeMethod || method === cloudFallbackMethod) retainForDispatchedUpload(); },
1970
1971
  };
1971
1972
  let jobUpdates: BridgeJobUpdate[] = [];
@@ -3545,7 +3546,7 @@ class BambuPrinterMCPServer {
3545
3546
  },
3546
3547
  {
3547
3548
  name: "counterpart_setup_fields",
3548
- description: "Counterpart contract (counterpart/1): the printers this server drives and the settings it reads for each, by .env variable name (first canonical, then aliases): label, hint, whether required, the model choices and the model each serial-number prefix names. Pass serial to get the model it names. Sends nothing to a printer and returns no configured values.",
3549
+ description: "Counterpart contract (counterpart/1): the printers this server drives and the settings it reads for each, by .env variable name (first canonical, then aliases): label, hint, whether required, the model choices and the model each serial-number prefix names, and whether camera_snapshot reads the printer's camera with only those settings (cameraSnapshot). Pass serial to get the model it names. Sends nothing to a printer and returns no configured values.",
3549
3550
  inputSchema: {
3550
3551
  type: "object",
3551
3552
  properties: { serial: { type: "string", maxLength: 64, description: "A Bambu serial number: model is the one it names, when known." } },
@@ -3709,7 +3710,7 @@ class BambuPrinterMCPServer {
3709
3710
  });
3710
3711
 
3711
3712
  // A designer's settings extracted for this call are removed when it settles.
3712
- this.server.setRequestHandler(CallToolRequestSchema, (request, extra) => withExtractedSettingsCleanup(async () => {
3713
+ this.server.setRequestHandler(CallToolRequestSchema, (request, extra) => withPrintDispatch(() => withExtractedSettingsCleanup(async () => {
3713
3714
  const { name, arguments: args } = request.params;
3714
3715
  const sendNativeCommand = (
3715
3716
  options: Parameters<typeof sendCommandWithBambuNative>[0],
@@ -5155,7 +5156,7 @@ class BambuPrinterMCPServer {
5155
5156
  : `Check parameters and try again. Error: ${message}`,
5156
5157
  message,
5157
5158
  tool: name,
5158
- ...(error instanceof PrinterRefusal ? { code: error.code } : {}),
5159
+ ...(error instanceof PrinterRefusal ? { code: error.code } : {}), ...(["print_3mf", "upload_gcode"].includes(name) ? { printOutcome: printOutcome(error) } : {}),
5159
5160
  // The slicer's own result.json; the message starts with its error_string and warnings.
5160
5161
  // A slicer failure always carries slicer_report: the plain sentence a person sees, the slicer's words for the log.
5161
5162
  // The report always says failed (a result.json that says success can still leave no output file).
@@ -5174,7 +5175,7 @@ class BambuPrinterMCPServer {
5174
5175
  isError: true,
5175
5176
  };
5176
5177
  }
5177
- }));
5178
+ })));
5178
5179
  }
5179
5180
 
5180
5181
  async startStdio() {
@@ -1,4 +1,4 @@
1
- import { PrinterRefusal } from "../refusal.js";
1
+ import { PrinterRefusal, markPrintCommandSent } from "../refusal.js";
2
2
  import {CameraStreams, type FrameOptions} from "./camera-stream.js";
3
3
  import {openTcpCameraSource, openRtspCameraSource} from "./camera-sources.js";
4
4
  import {cameraNumber} from "./camera-tools.js";
@@ -1273,6 +1273,7 @@ export class BambuImplementation {
1273
1273
  assertActive();
1274
1274
  if (legacyContainer) {
1275
1275
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
1276
+ markPrintCommandSent();
1276
1277
  try { await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remoteProjectPath })); } catch (error) { watcher.dispose(); throw error; }
1277
1278
  this.recordCheckedJob(host, serial, remoteProjectPath, requirements, resumeFile);
1278
1279
  const dispatch = await watcher.settled();
@@ -1354,6 +1355,7 @@ export class BambuImplementation {
1354
1355
  }
1355
1356
 
1356
1357
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
1358
+ markPrintCommandSent();
1357
1359
  try { await printer.publish(projectFileCmd); } catch (error) { watcher.dispose(); throw error; }
1358
1360
  this.recordCheckedJob(host, serial, remoteProjectPath, requirements, resumeFile);
1359
1361
  await new Promise((resolve) => setTimeout(resolve, 300));
@@ -2014,6 +2016,7 @@ export class BambuImplementation {
2014
2016
  const printer = await this.getPrinter(host, serial, token);
2015
2017
  assertActive();
2016
2018
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
2019
+ markPrintCommandSent();
2017
2020
  try { await invokeWithoutAck(printer, new GCodeFileCommand({ fileName: remotePath })); } catch (error) { watcher.dispose(); throw error; }
2018
2021
  this.recordCheckedJob(host, serial, remotePath, requirements, resumeFile);
2019
2022
  const dispatch = await watcher.settled();
package/src/refusal.ts CHANGED
@@ -1,7 +1,9 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+
1
3
  /**
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.
4
+ * A printer refusal with a stable diagnostic code, retained for existing clients.
5
+ * Counterpart uses structuredContent.printOutcome for dispatch truth, never
6
+ * these firmware-specific codes or the message.
5
7
  *
6
8
  * - printer-command-rejected: the printer refused the print command itself (for Bambu, HMS 0500-0500-0001-0007,
7
9
  * MQTT command verification); the file was uploaded and the command sent, but nothing is printing.
@@ -17,3 +19,19 @@ export class PrinterRefusal extends Error {
17
19
  this.name = "PrinterRefusal";
18
20
  }
19
21
  }
22
+
23
+ /** counterpart/1 dispatch-tool errors describe dispatch truth independently of firmware-specific codes. */
24
+ export type PrintOutcome = "not-sent" | "unknown" | "rejected";
25
+ const printDispatch = new AsyncLocalStorage<{ attempted: boolean }>();
26
+ export function withPrintDispatch<T>(run: () => T): T {
27
+ return printDispatch.run({ attempted: false }, run);
28
+ }
29
+ /** Call immediately before handing a print command to a transport. An acknowledgement may then be lost. */
30
+ export function markPrintCommandSent(): void {
31
+ const dispatch = printDispatch.getStore();
32
+ if (dispatch) dispatch.attempted = true;
33
+ }
34
+ export function printOutcome(error: unknown): PrintOutcome {
35
+ if (error instanceof PrinterRefusal && error.code === "printer-command-rejected") return "rejected";
36
+ return printDispatch.getStore()?.attempted === false ? "not-sent" : "unknown";
37
+ }