bambu-printer-mcp 1.1.91 → 1.1.93

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.
Files changed (69) hide show
  1. package/CONTRIBUTORS.md +2 -0
  2. package/README.md +8 -4
  3. package/dist/bambu-native.js +1 -1
  4. package/dist/cad/contracts.js +16 -7
  5. package/dist/cad/examples.d.ts +2 -1
  6. package/dist/cad/examples.js +13 -10
  7. package/dist/cad/serial.d.ts +1 -1
  8. package/dist/cad/serial.js +4 -6
  9. package/dist/cad-engine.js +17 -12
  10. package/dist/counterpart/info.d.ts +2 -0
  11. package/dist/counterpart/info.js +6 -1
  12. package/dist/counterpart/remote.js +1 -0
  13. package/dist/counterpart/schemas.d.ts +5 -0
  14. package/dist/counterpart/schemas.js +1 -0
  15. package/dist/counterpart/self-check.d.ts +79 -0
  16. package/dist/counterpart/self-check.js +163 -0
  17. package/dist/index.js +50 -24
  18. package/dist/printers/bambu.d.ts +6 -0
  19. package/dist/printers/bambu.js +59 -25
  20. package/dist/printers/report-merge.d.ts +12 -0
  21. package/dist/printers/report-merge.js +46 -0
  22. package/dist/safety/limits.d.ts +6 -0
  23. package/dist/safety/limits.js +8 -0
  24. package/dist/safety/print-file.js +2 -2
  25. package/dist/safety/printer-state.d.ts +4 -0
  26. package/dist/safety/printer-state.js +14 -1
  27. package/dist/stl/stl-manipulator.js +79 -20
  28. package/dist/studio-print-options.d.ts +9 -0
  29. package/dist/studio-print-options.js +34 -2
  30. package/dist/tool-annotations.js +1 -0
  31. package/package.json +6 -1
  32. package/src/bambu-native.ts +1 -1
  33. package/src/cad/contracts.ts +17 -7
  34. package/src/cad/examples/bag_clip.py +1 -0
  35. package/src/cad/examples/bistable_clicker.py +1 -0
  36. package/src/cad/examples/broom_grip.py +61 -0
  37. package/src/cad/examples/cable_clip.py +1 -0
  38. package/src/cad/examples/chainmail.py +1 -0
  39. package/src/cad/examples/desk_clamp_hook.py +91 -0
  40. package/src/cad/examples/desk_edge_cable_holder.py +55 -0
  41. package/src/cad/examples/drawer_divider.py +56 -0
  42. package/src/cad/examples/hinged_box.py +1 -0
  43. package/src/cad/examples/knurled_knob.py +1 -0
  44. package/src/cad/examples/loft_handle.py +1 -0
  45. package/src/cad/examples/organizer_tray.py +41 -0
  46. package/src/cad/examples/phone_stand.py +1 -0
  47. package/src/cad/examples/plant_pot.py +53 -0
  48. package/src/cad/examples/shelf_bracket.py +53 -0
  49. package/src/cad/examples/swept_hook.py +1 -0
  50. package/src/cad/examples/threaded_jar.py +1 -0
  51. package/src/cad/examples/trigger_capo.py +1 -0
  52. package/src/cad/examples/wall_hook.py +1 -0
  53. package/src/cad/examples.ts +13 -10
  54. package/src/cad/geometry.py +6 -0
  55. package/src/cad/serial.ts +4 -6
  56. package/src/cad-engine.ts +9 -3
  57. package/src/counterpart/info.ts +7 -1
  58. package/src/counterpart/remote.ts +1 -0
  59. package/src/counterpart/schemas.ts +3 -1
  60. package/src/counterpart/self-check.ts +164 -0
  61. package/src/index.ts +48 -20
  62. package/src/printers/bambu.ts +57 -24
  63. package/src/printers/report-merge.ts +48 -0
  64. package/src/safety/limits.ts +8 -0
  65. package/src/safety/print-file.ts +2 -2
  66. package/src/safety/printer-state.ts +13 -1
  67. package/src/stl/stl-manipulator.ts +75 -14
  68. package/src/studio-print-options.ts +33 -2
  69. package/src/tool-annotations.ts +1 -0
@@ -0,0 +1,163 @@
1
+ /**
2
+ * counterpart_self_check (counterpart/1): whether this install's own runtime dependencies and the bundled bambu-node
3
+ * patch loaded, so a client that updated the server can tell a broken install from a working one. Local only: it
4
+ * loads modules from this server's own install and sends nothing to a printer.
5
+ */
6
+ import fs from "node:fs";
7
+ import { createRequire } from "node:module";
8
+ import path from "node:path";
9
+ import { fileURLToPath } from "node:url";
10
+ import { COUNTERPART_CONTRACT } from "./schemas.js";
11
+ export const SELF_CHECK_OUTPUT_SCHEMA = {
12
+ type: "object",
13
+ properties: {
14
+ contract: { type: "string", const: COUNTERPART_CONTRACT },
15
+ server: { type: "object", properties: { name: { type: "string" }, version: { type: "string" } }, required: ["name", "version"] },
16
+ ok: { type: "boolean", description: "Every check passed, optional dependencies aside." },
17
+ checks: {
18
+ type: "array",
19
+ items: {
20
+ type: "object",
21
+ properties: { name: { type: "string" }, ok: { type: "boolean" }, optional: { type: "boolean" }, version: { type: "string" }, message: { type: "string" } },
22
+ required: ["name", "ok"],
23
+ },
24
+ },
25
+ },
26
+ required: ["contract", "server", "ok", "checks"],
27
+ };
28
+ const PACKAGE_JSON = new URL("../../package.json", import.meta.url);
29
+ /** The module each dependency is loaded through, where its package root is not importable on its own. */
30
+ const ENTRIES = {
31
+ "@modelcontextprotocol/sdk": "@modelcontextprotocol/sdk/server/index.js",
32
+ // Only its patch parser runs, at install (scripts/install-patches.mjs); its root is the CLI.
33
+ "patch-package": "patch-package/dist/patch/parse.js",
34
+ };
35
+ /** The version in the package.json of name that contains file, from this install. */
36
+ function installedVersion(file, name) {
37
+ for (let dir = path.dirname(file); dir !== path.dirname(dir); dir = path.dirname(dir)) {
38
+ const manifest = path.join(dir, "package.json");
39
+ if (!fs.existsSync(manifest))
40
+ continue;
41
+ try {
42
+ const parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
43
+ if (parsed?.name === name)
44
+ return typeof parsed.version === "string" ? parsed.version : undefined;
45
+ }
46
+ catch { /* a malformed manifest is not this package's */ }
47
+ }
48
+ return undefined;
49
+ }
50
+ /** The file specifier resolves to from this module (import.meta.resolve needs Node.js 18.19 or 20.6; older ones require). */
51
+ function resolveFromHere(specifier) {
52
+ return typeof import.meta.resolve === "function"
53
+ ? fileURLToPath(import.meta.resolve(specifier))
54
+ : createRequire(import.meta.url).resolve(specifier);
55
+ }
56
+ const message = (error) => error instanceof Error ? error.message : String(error);
57
+ /**
58
+ * Whether version meets declared, for the forms package.json uses: x.y.z exactly, ^x.y.z (the leftmost non-zero
59
+ * part stays) or ~x.y.z (the minor stays). Other forms are not judged (undefined).
60
+ */
61
+ export function meetsDeclared(version, declared) {
62
+ const want = /^([~^]?)(\d+)\.(\d+)\.(\d+)$/.exec(declared.trim());
63
+ const have = /^(\d+)\.(\d+)\.(\d+)(-)?/.exec(version);
64
+ if (!want || !have)
65
+ return undefined;
66
+ // A prerelease (3.22.21-beta.1) meets none of these forms.
67
+ if (have[4])
68
+ return false;
69
+ const [w0, w1, w2] = want.slice(2).map(Number), [h0, h1, h2] = have.slice(1, 4).map(Number);
70
+ const order = h0 - w0 || h1 - w1 || h2 - w2;
71
+ if (want[1] === "")
72
+ return order === 0;
73
+ if (order < 0)
74
+ return false;
75
+ if (want[1] === "~")
76
+ return h0 === w0 && h1 === w1;
77
+ return w0 > 0 ? h0 === w0 : w1 > 0 ? h0 === 0 && h1 === w1 : h0 === 0 && h1 === 0 && h2 === w2;
78
+ }
79
+ /** Why the installed version does not meet package.json's, or undefined when it does. A form not judged is a failure. */
80
+ export function versionProblem(name, version, declared) {
81
+ const meets = meetsDeclared(version ?? "", declared);
82
+ if (meets === true)
83
+ return undefined;
84
+ if (meets === undefined && version !== undefined)
85
+ return `This check cannot judge ${name}'s declared version "${declared}"; ${version} is installed.`;
86
+ return `This server needs ${name} ${declared}; ${version ?? "an unknown version"} is installed.`;
87
+ }
88
+ /** One dependency: it resolves from this install, loads, and its installed version meets package.json's. */
89
+ async function dependencyCheck(name, declared) {
90
+ const specifier = ENTRIES[name] ?? name;
91
+ try {
92
+ const file = resolveFromHere(specifier);
93
+ const version = installedVersion(file, name);
94
+ await import(specifier);
95
+ const problem = versionProblem(name, version, declared);
96
+ if (problem)
97
+ return { name, ok: false, ...(version ? { version } : {}), message: problem };
98
+ return { name, ok: true, ...(version ? { version } : {}) };
99
+ }
100
+ catch (error) {
101
+ return { name, ok: false, message: `${name} did not load: ${message(error)}` };
102
+ }
103
+ }
104
+ /** Every hunk of the bundled patch is in the installed bambu-node: a read-only reverse dry run, as postinstall checks. */
105
+ function patchApplied(version) {
106
+ const require = createRequire(import.meta.url);
107
+ const root = fs.realpathSync(path.dirname(require.resolve("bambu-node/package.json")));
108
+ const { parsePatchFile } = require("patch-package/dist/patch/parse.js");
109
+ const { executeEffects } = require("patch-package/dist/patch/apply.js");
110
+ const { reversePatch } = require("patch-package/dist/patch/reverse.js");
111
+ const patch = fs.readFileSync(new URL(`../../patches/bambu-node+${version}.patch`, import.meta.url), "utf8");
112
+ const effects = parsePatchFile(patch).map((effect) => {
113
+ if (effect.type !== "patch" || !effect.path.startsWith("node_modules/bambu-node/"))
114
+ throw new Error("the bundled patch has an unexpected target");
115
+ return { ...effect, path: effect.path.slice("node_modules/bambu-node/".length) };
116
+ });
117
+ try {
118
+ executeEffects(reversePatch(effects), { cwd: root, dryRun: true, bestEffort: false });
119
+ }
120
+ catch {
121
+ throw new Error(`the installed bambu-node ${version} is missing part of this server's patch`);
122
+ }
123
+ }
124
+ /**
125
+ * The bundled patch (patches/bambu-node+<version>.patch) is in the installed bambu-node, and the loaded module
126
+ * behaves patched: it adds the H2-series and later printers to model detection, so an unpatched bambu-node throws
127
+ * "Printer model not supported!" on an H2D's version report. The report is read in memory, without a connection.
128
+ */
129
+ async function bambuNodePatchCheck(version) {
130
+ const name = "bambu-node patch";
131
+ try {
132
+ if (!version)
133
+ throw new Error("package.json names no bambu-node version");
134
+ patchApplied(version);
135
+ const { BambuClient } = await import("bambu-node");
136
+ const serial = "094SELFCHECK";
137
+ const client = new BambuClient({ host: "127.0.0.1", serialNumber: serial, accessToken: "self-check" });
138
+ await client.onMessage(JSON.stringify({ info: { command: "get_version", module: [{ name: "ota", sn: serial }] } }), `device/${serial}/report`);
139
+ const model = client.data?.model;
140
+ return model === "H2D" ? { name, ok: true } : { name, ok: false, message: `bambu-node read an H2D as ${String(model)}; reinstall this server so its patch is applied.` };
141
+ }
142
+ catch (error) {
143
+ return { name, ok: false, message: `bambu-node is not patched: ${message(error)}. Reinstall this server so its patch is applied.` };
144
+ }
145
+ }
146
+ export async function selfCheck(server) {
147
+ let dependencies = {};
148
+ const checks = [];
149
+ try {
150
+ const manifest = JSON.parse(fs.readFileSync(PACKAGE_JSON, "utf8"));
151
+ dependencies = manifest.dependencies ?? {};
152
+ if (manifest.version !== server.version)
153
+ checks.push({ name: "package", ok: false, version: String(manifest.version), message: `The running server is ${server.version}, but its install is ${manifest.version}; restart it.` });
154
+ else
155
+ checks.push({ name: "package", ok: true, version: server.version });
156
+ }
157
+ catch (error) {
158
+ checks.push({ name: "package", ok: false, message: `Could not read this server's package.json: ${message(error)}` });
159
+ }
160
+ checks.push(...await Promise.all(Object.entries(dependencies).map(([name, declared]) => dependencyCheck(name, declared))));
161
+ checks.push(await bambuNodePatchCheck(dependencies["bambu-node"]));
162
+ return { contract: COUNTERPART_CONTRACT, server, ok: checks.every(check => check.ok || check.optional), checks };
163
+ }
package/dist/index.js CHANGED
@@ -45,7 +45,7 @@ import { resolveStudioPrintOptions, usedNozzleCount } from "./studio-print-optio
45
45
  import { inspectPrintFile } from "./safety/print-file.js";
46
46
  import { previewPrintFile } from "./safety/print-preview.js";
47
47
  import { loadSafe3mfArchive } from "./safety/archive.js";
48
- import { SERIAL_MODELS, externalStorageState, validatePrinterState } from "./safety/printer-state.js";
48
+ import { SERIAL_MODELS, internalPrintingSupported, externalStorageState, validatePrinterState } from "./safety/printer-state.js";
49
49
  import { isDualNozzleModel } from "./safety/limits.js";
50
50
  import { withPrinterOperation, withPrintSnapshot, uniquePrintName } from "./safety/artifact.js";
51
51
  import { detectProfilesRoot } from "./slicer/profile-flatten.js";
@@ -57,6 +57,7 @@ import { DESIGN_PROMPTS, FDM_CAPABILITY_GUIDANCE, FDM_CAPABILITY_RESOURCE, FDM_C
57
57
  import { bambuProgress, offlineProgress } from "./counterpart/progress.js";
58
58
  import { makeCounterpart3mf } from "./counterpart/make-3mf.js";
59
59
  import { MAKE_3MF_OUTPUT_SCHEMA, PRINT_PROGRESS_OUTPUT_SCHEMA, PRINTER_INFO_OUTPUT_SCHEMA } from "./counterpart/schemas.js";
60
+ import { SELF_CHECK_OUTPUT_SCHEMA, selfCheck } from "./counterpart/self-check.js";
60
61
  import { parseProcessOverrides } from "./slicer/process-overrides.js";
61
62
  import { PRINT_QUALITY_PROPERTIES, withPrintQuality } from "./slicer/print-quality.js";
62
63
  import { PrinterRefusal, withPrintDispatch, markPrintCommandSent, printOutcome } from "./refusal.js";
@@ -125,7 +126,7 @@ const SERVER_INFO = {
125
126
  /** Tools that declare an outputSchema: they always return structuredContent, and errors carry none. */
126
127
  const OUTPUT_SCHEMA_TOOLS = new Set([
127
128
  "cad_status", "cad_setup", "cad_run", "cad_check_fit", "cad_examples",
128
- "counterpart_printer_info", "counterpart_print_progress", "counterpart_make_3mf",
129
+ "counterpart_printer_info", "counterpart_self_check", "counterpart_print_progress", "counterpart_make_3mf",
129
130
  "counterpart_discover_printers", "counterpart_setup_fields", "counterpart_propose_filaments",
130
131
  "fusion_mcp_status", "fusion_mcp_new_design", "fusion_mcp_export",
131
132
  "camera_stream_start", "camera_frame", "camera_stream_stop",
@@ -146,19 +147,26 @@ function withEmergencyMqttTimeout(send) {
146
147
  return Promise.race([Promise.resolve().then(() => send(controller.signal)), timeout]).finally(() => clearTimeout(timer));
147
148
  }
148
149
  /**
149
- * Whether an X2D native print stores its job on the SD card or USB stick
150
+ * Whether a native print stores its job on the SD card or USB stick
150
151
  * (true) or internal storage (eMMC). An explicit try_emmc_print wins, then
151
152
  * BAMBU_NATIVE_TRY_EMMC_PRINT read as the helper reads it; otherwise a ready
152
153
  * card is used, as OrcaSlicer does, so the job can be reprinted from the
153
- * printer and read over FTPS.
154
+ * printer and read over FTPS. X1C internal printing additionally requires
155
+ * the capability bit from fresh status, including at final dispatch.
154
156
  */
155
- function nativeExternalStorage(tryEmmcPrint, raw) {
156
- if (tryEmmcPrint !== undefined)
157
- return !tryEmmcPrint;
157
+ function nativeExternalStorage(tryEmmcPrint, raw, model) {
158
158
  const configured = process.env.BAMBU_NATIVE_TRY_EMMC_PRINT?.trim();
159
- if (configured)
160
- return !["1", "true", "TRUE", "yes"].includes(configured);
161
- return externalStorageState(raw) === "normal";
159
+ const external = tryEmmcPrint !== undefined ? !tryEmmcPrint
160
+ : configured ? !["1", "true", "TRUE", "yes"].includes(configured)
161
+ : externalStorageState(raw) === "normal";
162
+ if (!external)
163
+ assertNativeInternalStorage(model, raw);
164
+ return external;
165
+ }
166
+ function assertNativeInternalStorage(model, raw) {
167
+ if (model === "x1c" && !internalPrintingSupported(raw)) {
168
+ throw new Error("X1C internal printing is not advertised in the fresh status. Use a ready SD card or USB stick; unsupported internal storage requests are refused.");
169
+ }
162
170
  }
163
171
  function requestedPrintNozzles(args) {
164
172
  if (args.nozzle_diameters !== undefined && args.nozzle_diameter !== undefined) {
@@ -209,6 +217,11 @@ function callerPrintOptions(args) {
209
217
  // the dual-nozzle H2 path. Keep it in this gate so pre-sliced multi-filament
210
218
  // jobs take the correct branch instead of the legacy 5-slot mapping.
211
219
  const H2_BAMBU_MODELS = new Set(["h2d", "h2dpro", "h2s", "h2c", "x2d"]);
220
+ // Models that may print and upload over connection_mode=bambu_native. X2D
221
+ // defaults to it. X1C opts in: firmware 01.12.00.00 was seen refusing every
222
+ // direct FTPS STOR with 553 while Bambu Studio's plug-in still printed.
223
+ const NATIVE_ROUTE_MODELS = new Set(["x2d", "x1c"]);
224
+ const NATIVE_ROUTE_RESTRICTION = "connection_mode=bambu_native is restricted to X2D and X1C.";
212
225
  const VALID_BED_TYPES = ["textured_plate", "cool_plate", "engineering_plate", "hot_plate", "supertack_plate"];
213
226
  const VALID_NOZZLE_TYPES = ["stainless_steel", "hardened_steel", "tungsten_carbide", "brass"];
214
227
  /** The installed hotend material. Bambu machine presets assume the stock nozzle; the print gate compares this with the printer. */
@@ -1430,7 +1443,7 @@ class BambuPrinterMCPServer {
1430
1443
  const { threeMFPath, autoSliced } = await this.ensurePrintableThreeMFPath(args, printModel, printPreset, printBedType);
1431
1444
  const { useAMS, finalAmsMapping, finalAmsSlots } = await this.resolveAmsPrintSettings(threeMFPath, args, host, bambuSerial, bambuToken, printModel, printNozzle);
1432
1445
  if (native && args.use_ams !== false && !useAMS) {
1433
- throw new Error("Native X2D printing requires ams_mapping, ams_slots, auto_match_ams, or explicit use_ams: false for an external spool.");
1446
+ throw new Error("Native printing requires ams_mapping, ams_slots, auto_match_ams, or explicit use_ams: false for an external spool.");
1434
1447
  }
1435
1448
  const threeMfFilename = path.basename(threeMFPath);
1436
1449
  const projectName = String(args?.project_name || args?.task_name || threeMfFilename.replace(/\.3mf$/i, ''));
@@ -1531,7 +1544,7 @@ class BambuPrinterMCPServer {
1531
1544
  };
1532
1545
  assertActive();
1533
1546
  if (native) {
1534
- const externalStorage = nativeExternalStorage(args?.try_emmc_print, confirmedStatus.raw);
1547
+ const externalStorage = nativeExternalStorage(args?.try_emmc_print, confirmedStatus.raw, printModel);
1535
1548
  if (externalStorage && externalStorageState(confirmedStatus.raw) !== "normal") {
1536
1549
  throw new Error("External storage was requested, but the printer reports no ready SD card or USB stick.");
1537
1550
  }
@@ -1561,6 +1574,8 @@ class BambuPrinterMCPServer {
1561
1574
  if (externalStorage && externalStorageState(dispatchStatus.raw) !== "normal") {
1562
1575
  throw new Error("The printer's SD card or USB stick is no longer ready. Check it and start the print again.");
1563
1576
  }
1577
+ if (!externalStorage)
1578
+ assertNativeInternalStorage(printModel, dispatchStatus.raw);
1564
1579
  assertActive();
1565
1580
  this.bambu.recordFlightDispatch(devIp, devId, remoteFileName, requirements, resumeFile);
1566
1581
  markPrintCommandSent();
@@ -1664,18 +1679,18 @@ class BambuPrinterMCPServer {
1664
1679
  async print3mfViaBambuNative(args, host, bambuSerial, bambuToken, onUpdate, signal) {
1665
1680
  assertBambuNativeAvailable();
1666
1681
  const model = await this.resolveBambuModel(args.bambu_model);
1667
- if (model !== "x2d")
1668
- throw new Error("connection_mode=bambu_native is restricted to X2D.");
1682
+ if (!NATIVE_ROUTE_MODELS.has(model))
1683
+ throw new Error(NATIVE_ROUTE_RESTRICTION);
1669
1684
  return this.print3mfViaBambuNetwork({ ...args, bambu_model: model, connection_type: "lan", bambu_network_method: "start_local_print" }, host, bambuSerial, bambuToken, { onUpdate, signal });
1670
1685
  }
1671
1686
  async uploadFileViaBambuNative(args, host, bambuSerial, bambuToken, onUpdate, signal) {
1672
1687
  if (args.print)
1673
1688
  throw new Error("Native upload never starts printing; use print_3mf.");
1674
1689
  // Resolve and enforce the model first, as the print path does, so a
1675
- // non-X2D request is never told to install the native helper.
1690
+ // request for another model is never told to install the native helper.
1676
1691
  const model = await this.resolveBambuModel(args.bambu_model);
1677
- if (model !== "x2d")
1678
- throw new Error("connection_mode=bambu_native is restricted to X2D.");
1692
+ if (!NATIVE_ROUTE_MODELS.has(model))
1693
+ throw new Error(NATIVE_ROUTE_RESTRICTION);
1679
1694
  assertBambuNativeAvailable();
1680
1695
  const unsupported = ["use_ams", "ams_mapping", "ams_mapping2", "ams_mapping_info", "nozzle_mapping", "nozzles_info",
1681
1696
  "bed_leveling", "flow_calibration", "vibration_calibration", "layer_inspect", "timelapse"];
@@ -2454,7 +2469,7 @@ class BambuPrinterMCPServer {
2454
2469
  nozzle_mapping: { type: "string", description: "Raw JSON string for FULU PrintParams nozzle_mapping." },
2455
2470
  nozzles_info: { type: "string", description: "Raw JSON string for FULU PrintParams nozzles_info." },
2456
2471
  bed_leveling: { type: "boolean", description: "Auto bed leveling on or off. Omit to send what Bambu Studio's Send dialog would: the choice saved in BambuStudio.conf for this printer, else Studio's default." },
2457
- flow_calibration: { type: "boolean", description: "Flow calibration on or off. Omit to send what Bambu Studio's Send dialog would (auto on P1/P1S)." },
2472
+ flow_calibration: { type: "boolean", description: "Flow calibration task boolean. Omission resolves Studio settings (auto on P1/P1S); direct MQTT sends false for auto but does not transmit the integer auto mode. The result calibration report distinguishes resolved and transmitted options." },
2458
2473
  vibration_calibration: { type: "boolean", description: "Vibration calibration (default false, as Bambu Studio sends)." },
2459
2474
  layer_inspect: { type: "boolean", description: "First-layer inspection where supported (default true, as Bambu Studio sends)." },
2460
2475
  timelapse: { type: "boolean", description: "Enable timelapse recording in FULU PrintParams (default: false)." },
@@ -2536,7 +2551,7 @@ class BambuPrinterMCPServer {
2536
2551
  connection_mode: {
2537
2552
  type: "string",
2538
2553
  enum: ["lan_mqtt_ftps", "bambu_native"],
2539
- description: "Upload transport; bambu_native uses the installed Bambu networking plug-in for X2D and never starts printing."
2554
+ description: "Upload transport; bambu_native uses the installed Bambu networking plug-in for X2D or X1C and never starts printing."
2540
2555
  },
2541
2556
  bambu_model: {
2542
2557
  type: "string",
@@ -2845,9 +2860,9 @@ class BambuPrinterMCPServer {
2845
2860
  connection_mode: {
2846
2861
  type: "string",
2847
2862
  enum: ["lan_mqtt_ftps", "bambu_network", "bambu_native", "bambu_connect"],
2848
- description: "Print path: bambu_connect hands a printable file to the signed-in Bambu Connect app for cloud-mode review; X2D otherwise defaults to bambu_native (Bambu Studio's installed local networking plug-in, storing the job on a ready SD card or USB stick, otherwise internal eMMC); lan_mqtt_ftps is the legacy direct MQTT/FTPS path; bambu_network uses the FULU bridge."
2863
+ description: "Print path: bambu_connect hands a printable file to the signed-in Bambu Connect app for cloud-mode review; X2D otherwise defaults to bambu_native (Bambu Studio's installed local networking plug-in, storing the job on a ready SD card or USB stick, otherwise internal eMMC); X1C may opt in to bambu_native, for example when its firmware refuses FTPS uploads with 553; lan_mqtt_ftps is the legacy direct MQTT/FTPS path; bambu_network uses the FULU bridge."
2849
2864
  },
2850
- try_emmc_print: { type: "boolean", description: "X2D native printing: true stores the job on internal storage (eMMC), false on the SD card or USB stick (refused unless the printer reports one ready). Omit to use the card when ready, else eMMC; BAMBU_NATIVE_TRY_EMMC_PRINT sets a server default." },
2865
+ try_emmc_print: { type: "boolean", description: "X2D native printing: true stores the job on internal storage (eMMC), false on the SD card or USB stick (refused unless the printer reports one ready). Omit to use the card when ready, else eMMC; X1C requires fresh advertised internal-printing support before using eMMC. BAMBU_NATIVE_TRY_EMMC_PRINT sets a server default." },
2851
2866
  connection_type: { type: "string", enum: ["cloud", "lan"], description: "BambuNetwork connection type when connection_mode is bambu_network; cloud uses restored internet printing, lan uses local bridge printing." },
2852
2867
  bambu_network_method: { type: "string", enum: BAMBU_NETWORK_PRINT_METHODS, description: "FULU print method when connection_mode is bambu_network; defaults to start_local_print for lan, and for cloud to Bambu Studio's order: start_local_print_with_record, then start_print if that fails." },
2853
2868
  dev_id: { type: "string", description: "Bambu device id for FULU BambuNetwork printing; defaults to BAMBU_DEV_ID or BAMBU_SERIAL." },
@@ -2897,7 +2912,7 @@ class BambuPrinterMCPServer {
2897
2912
  description: "When true, match the sliced 3MF's tray_info_idx requirements against live AMS inventory and use the resulting ams_slots. Ignored when ams_mapping or ams_slots is provided."
2898
2913
  },
2899
2914
  bed_leveling: { type: "boolean", description: "Auto bed leveling on or off. Omit to send what Bambu Studio's Send dialog would: the choice saved in BambuStudio.conf for this printer, else Studio's default." },
2900
- flow_calibration: { type: "boolean", description: "Flow calibration on or off. Omit to send what Bambu Studio's Send dialog would (auto on P1/P1S)." },
2915
+ flow_calibration: { type: "boolean", description: "Flow calibration task boolean. Omission resolves Studio settings (auto on P1/P1S); direct MQTT sends false for auto but does not transmit the integer auto mode. The result calibration report distinguishes resolved and transmitted options." },
2901
2916
  vibration_calibration: { type: "boolean", description: "Vibration calibration (default false, as Bambu Studio sends)." },
2902
2917
  timelapse: { type: "boolean", description: "Enable timelapse recording (default: false)" },
2903
2918
  slicer_profile: { type: "string", description: "Path to the slicer profile/config file for auto-slicing (optional)." },
@@ -2933,7 +2948,7 @@ class BambuPrinterMCPServer {
2933
2948
  description: "Bed plate type currently installed (default: textured_plate)"
2934
2949
  },
2935
2950
  bed_leveling: { type: "boolean", description: "Auto bed leveling on or off. Omit to send what Bambu Studio's Send dialog would: the choice saved in BambuStudio.conf for this printer, else Studio's default." },
2936
- flow_calibration: { type: "boolean", description: "Flow calibration on or off. Omit to send what Bambu Studio's Send dialog would (auto on P1/P1S)." },
2951
+ flow_calibration: { type: "boolean", description: "Flow calibration task boolean. Omission resolves Studio settings (auto on P1/P1S); direct MQTT sends false for auto but does not transmit the integer auto mode. The result calibration report distinguishes resolved and transmitted options." },
2937
2952
  vibration_calibration: { type: "boolean", description: "Vibration calibration (default false, as Bambu Studio sends)." },
2938
2953
  timelapse: { type: "boolean", description: "Enable timelapse recording (default: false)" },
2939
2954
  slicer_profile: { type: "string", description: "Path to the slicer profile/config file for auto-slicing (optional)." },
@@ -3044,6 +3059,12 @@ class BambuPrinterMCPServer {
3044
3059
  },
3045
3060
  outputSchema: PRINTER_INFO_OUTPUT_SCHEMA
3046
3061
  },
3062
+ {
3063
+ name: "counterpart_self_check",
3064
+ description: "Counterpart contract (counterpart/1): whether this install's own runtime dependencies and its bundled bambu-node patch loaded, each with its installed version. Run it after an update; ok is false when a check failed, with a message saying which. Sends nothing to the printer.",
3065
+ inputSchema: { type: "object", properties: {} },
3066
+ outputSchema: SELF_CHECK_OUTPUT_SCHEMA
3067
+ },
3047
3068
  {
3048
3069
  name: "counterpart_discover_printers",
3049
3070
  description: "Counterpart contract (counterpart/1): Bambu printers on the local network, from their own SSDP announcements (UDP 2021), with serial, model (as bambu_model names it), name and firmware. Listens for duration_ms (default 4000). network is \"unavailable\" when another app holds the port. Never connects to or authenticates with a printer.",
@@ -3299,7 +3320,9 @@ class BambuPrinterMCPServer {
3299
3320
  ? linuxEmergency(() => nativeCommand(), signal => this.bambu.sendStopOverMqtt(host, bambuSerial, bambuToken, signal))
3300
3321
  : nativeCommand;
3301
3322
  }
3302
- if (route.mode === "bambu_native")
3323
+ // Native controls are X2D-only. Another model printed natively (X1C)
3324
+ // is stopped, paused and resumed over direct MQTT, as its default route is.
3325
+ if (route.mode === "bambu_native" && x2dTarget)
3303
3326
  throw new Error(nativeUnavailableReason());
3304
3327
  if (route.mode !== "bambu_network")
3305
3328
  return undefined;
@@ -4359,6 +4382,9 @@ class BambuPrinterMCPServer {
4359
4382
  sliced: args?.sliced === true, names: colourNames() });
4360
4383
  break;
4361
4384
  }
4385
+ case "counterpart_self_check":
4386
+ result = await selfCheck(SERVER_INFO);
4387
+ break;
4362
4388
  case "counterpart_printer_info":
4363
4389
  result = bambuPrinterInfo({ server: SERVER_INFO, host, serial: bambuSerial, model: this.displayModel(args, bambuSerial), slicerType: normalizeSlicerType(DEFAULT_SLICER_TYPE) });
4364
4390
  break;
@@ -2,6 +2,12 @@ import { FlightRecords, type PrintGeometry } from "../counterpart/flight-record.
2
2
  import { CameraStreams, type FrameOptions } from "./camera-stream.js";
3
3
  import { inspectPrintFile, type PrintFileInspection } from "../safety/print-file.js";
4
4
  import { type PrinterStateRequirements } from "../safety/printer-state.js";
5
+ /**
6
+ * X1C firmware 01.12.00.00 was seen refusing every FTPS STOR with
7
+ * "553 Could not create file." (card ready and writable, Developer Mode on)
8
+ * while Bambu Studio's networking plug-in still printed. Name that route.
9
+ */
10
+ export declare function ftpsRefusalHint(error: unknown, model: string | undefined): string;
5
11
  export declare function assertDirectPrintSupported(model: string | undefined, serial?: string): void;
6
12
  interface BambuPrintOptionsInternal {
7
13
  /** Bytes sent to the printer so far over FTPS, and the file's size (LAN route). */
@@ -20,9 +20,10 @@ import { bridgeAmsMapping2Entry, bridgeAmsMappingValue, externalTrayForNozzle, d
20
20
  import { describeHmsKey, hiddenHmsKeys, hiddenHmsNotices, reportedHmsKey, unchippedNozzles, validatePrinterState, manualHeatingRequirements } from "../safety/printer-state.js";
21
21
  import { withPrinterOperation, withPrintSnapshot, uniquePrintName, normalizedRemotePath, cancelPendingPrinterOperations } from "../safety/artifact.js";
22
22
  import { RTSP_CAMERA_MODELS, TCP_CAMERA_MODELS } from "./camera-models.js";
23
- import { resolveStudioPrintOptions, usedNozzleCount } from "../studio-print-options.js";
23
+ import { directPrintOptionReport, resolveStudioPrintOptions, usedNozzleCount } from "../studio-print-options.js";
24
24
  import { Client as FTPClient } from "basic-ftp";
25
25
  import { uploadBytes } from "./ftp-upload.js";
26
+ import { mergeBambuReport } from "./report-merge.js";
26
27
  import * as mqtt from "mqtt";
27
28
  import { BambuClient, GCodeFileCommand, GCodeLineCommand, PushAllCommand, UpdateFanCommand, UpdateLightCommand, } from "bambu-node";
28
29
  /**
@@ -143,6 +144,19 @@ const MODEL_ID_TO_NAME = {
143
144
  C13: "X1E",
144
145
  };
145
146
  const H2_MODEL_NAMES = new Set(["h2", "h2c", "h2d", "h2dpro", "h2d pro", "h2s", "x2d"]);
147
+ /**
148
+ * X1C firmware 01.12.00.00 was seen refusing every FTPS STOR with
149
+ * "553 Could not create file." (card ready and writable, Developer Mode on)
150
+ * while Bambu Studio's networking plug-in still printed. Name that route.
151
+ */
152
+ export function ftpsRefusalHint(error, model) {
153
+ const message = error instanceof Error ? error.message : String(error);
154
+ if (normalizeModel(model) !== "x1c" || (error?.code !== 553 && !/^553\b/.test(message)))
155
+ return "";
156
+ return ' X1C firmware 01.12.00.00 has been seen refusing every direct FTPS upload this way. ' +
157
+ 'Retry with connection_mode: "bambu_native", which uploads through Bambu Studio\'s networking plug-in ' +
158
+ '(on macOS, first run npm run build:native in the package directory; on Linux, bambu-printer-mcp-native-setup).';
159
+ }
146
160
  export function assertDirectPrintSupported(model, serial) {
147
161
  if (model?.trim().toLowerCase() === "x2d" || serial?.trim().toUpperCase().startsWith("20P")) {
148
162
  throw new Error("X2D direct printing is not supported through legacy MQTT/FTPS. Use the native eMMC route via print_3mf (macOS, or Linux with the native helper installed). " +
@@ -342,11 +356,34 @@ class BambuClientStore {
342
356
  if (!update || Object.keys(update).length === 0) {
343
357
  return;
344
358
  }
345
- const previous = this.reportSnapshots.get(key) || {};
346
- this.reportSnapshots.set(key, { ...previous, ...update });
359
+ this.reportSnapshots.set(key, mergeBambuReport(this.reportSnapshots.get(key), update));
347
360
  this.reportTimes.set(key, Date.now());
348
361
  this.resolveInitialReport(key);
349
362
  }
363
+ /** Merges the printer's reports into its snapshot as they arrive (tests feed a client without a connection). */
364
+ watchReports(printer, host, serial, key) {
365
+ printer.on("rawMessage", (_topic, payload) => {
366
+ try {
367
+ const parsed = JSON.parse(payload.toString());
368
+ const printMessage = parsed?.print;
369
+ if (printMessage && typeof printMessage === "object") {
370
+ this.updateReportSnapshot(key, printMessage);
371
+ this.reportObserved(host, serial, key);
372
+ }
373
+ }
374
+ catch {
375
+ // Ignore unrelated payloads.
376
+ }
377
+ });
378
+ // bambu-node passes its whole merged report and then what changed. Only the change is merged here, so a field the
379
+ // printer has not sent again (the previous job's layer) is not copied back over this merge's own reset.
380
+ printer.on("printer:dataUpdate", (_data, changed) => {
381
+ if (!changed || typeof changed !== "object")
382
+ return;
383
+ this.updateReportSnapshot(key, changed);
384
+ this.reportObserved(host, serial, key);
385
+ });
386
+ }
350
387
  reportObserved(host, serial, key) {
351
388
  const report = this.reportSnapshots.get(key);
352
389
  if (!report || !this.onReport)
@@ -434,23 +471,7 @@ class BambuClientStore {
434
471
  accessToken: token,
435
472
  });
436
473
  this.ensureInitialReportPromise(key);
437
- printer.on("rawMessage", (_topic, payload) => {
438
- try {
439
- const parsed = JSON.parse(payload.toString());
440
- const printMessage = parsed?.print;
441
- if (printMessage && typeof printMessage === "object") {
442
- this.updateReportSnapshot(key, printMessage);
443
- this.reportObserved(host, serial, key);
444
- }
445
- }
446
- catch {
447
- // Ignore unrelated payloads.
448
- }
449
- });
450
- printer.on("printer:dataUpdate", (data) => {
451
- this.updateReportSnapshot(key, data);
452
- this.reportObserved(host, serial, key);
453
- });
474
+ this.watchReports(printer, host, serial, key);
454
475
  printer.on("client:connect", () => {
455
476
  this.printers.set(key, printer);
456
477
  this.initialConnectionPromises.delete(key);
@@ -989,12 +1010,13 @@ export class BambuImplementation {
989
1010
  });
990
1011
  const resumeFile = await checkedFile(inspection, options.filePath);
991
1012
  // The options Bambu Studio's Send dialog would send; explicit ones win.
992
- const studio = resolveStudioPrintOptions(model, {
1013
+ const caller = {
993
1014
  bedLeveling: options.bedLeveling, flowCalibration: options.flowCalibration,
994
1015
  vibrationCalibration: options.vibrationCalibration, layerInspect: options.layerInspect,
995
1016
  autoBedLeveling: options.autoBedLeveling, autoFlowCali: options.autoFlowCali,
996
1017
  autoOffsetCali: options.autoOffsetCali, extruderCaliManualMode: options.extruderCaliManualMode,
997
- }, { usedNozzles: usedNozzleCount(inspection) });
1018
+ };
1019
+ const studio = resolveStudioPrintOptions(model, caller, { usedNozzles: usedNozzleCount(inspection) });
998
1020
  const projectMetadata = await this.resolveProjectFileMetadata(options.filePath, options.plateIndex, inspection.plateInternalPath);
999
1021
  // Send project_file command via bambu-node MQTT (bypasses bambu-js
1000
1022
  // hardcoded use_ams=true and missing ams_mapping support)
@@ -1115,7 +1137,7 @@ export class BambuImplementation {
1115
1137
  }
1116
1138
  catch (error) {
1117
1139
  // Nothing has been sent to the printer but (part of) a file, so the print certainly did not start.
1118
- throw new PrinterRefusal("printer-upload-failed", `The print file did not reach the printer (${error instanceof Error ? error.message : String(error)}). No print was started.`);
1140
+ throw new PrinterRefusal("printer-upload-failed", `The print file did not reach the printer (${error instanceof Error ? error.message : String(error)}). No print was started.${ftpsRefusalHint(error, model)}`);
1119
1141
  }
1120
1142
  // Uploads can be long. Recheck current state before the command is dispatched.
1121
1143
  const dispatchStatus = await this.getSafetyStatus(host, serial, token);
@@ -1141,6 +1163,7 @@ export class BambuImplementation {
1141
1163
  const dispatch = await watcher.settled();
1142
1164
  return {
1143
1165
  status: "success", dispatch, remoteProjectPath,
1166
+ calibration: directPrintOptionReport(caller, studio, {}),
1144
1167
  message: dispatch === "started"
1145
1168
  ? `The printer accepted and started the checked gcode.3mf print: ${options.projectName}`
1146
1169
  : `Uploaded the checked gcode.3mf and sent the print command for ${options.projectName}; the printer has not reported starting yet. ` +
@@ -1215,6 +1238,7 @@ export class BambuImplementation {
1215
1238
  },
1216
1239
  };
1217
1240
  }
1241
+ const calibration = directPrintOptionReport(caller, studio, projectFileCmd.print);
1218
1242
  const watcher = this.watchDispatch(printer, host, serial, token, dispatchStatus, assertActive);
1219
1243
  this.recordFlightDispatch(host, serial, remoteProjectPath, requirements, resumeFile);
1220
1244
  markPrintCommandSent();
@@ -1230,6 +1254,7 @@ export class BambuImplementation {
1230
1254
  const dispatch = await watcher.settled();
1231
1255
  return {
1232
1256
  status: "success",
1257
+ calibration,
1233
1258
  dispatch,
1234
1259
  message: dispatch === "started"
1235
1260
  ? `The printer accepted and started the checked 3MF print: ${options.projectName}`
@@ -1789,8 +1814,17 @@ export class BambuImplementation {
1789
1814
  const destination = path.posix.join(path.posix.dirname(remotePath), uniquePrintName(remotePath));
1790
1815
  if (upload)
1791
1816
  await upload(snapshot, destination, assertActive);
1792
- else
1793
- await this.ftpUpload(host, token, snapshot, `/${destination}`);
1817
+ else {
1818
+ try {
1819
+ await this.ftpUpload(host, token, snapshot, `/${destination}`);
1820
+ }
1821
+ catch (error) {
1822
+ const hint = ftpsRefusalHint(error, model);
1823
+ if (hint && error instanceof Error)
1824
+ error.message += hint;
1825
+ throw error;
1826
+ }
1827
+ }
1794
1828
  return { status: "success", uploaded: true, remotePath: destination, printRequested: false, inspected: printable };
1795
1829
  }));
1796
1830
  }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Merging Bambu MQTT reports. P1/A1 printers push only what changed, so a merged report keeps every field until the
3
+ * printer sends it again. A new job's first pushes can carry its name and layer count before its layer number, and the
4
+ * previous job's last layer then read against the new total ("315/150"). Until the new job reports its own progress,
5
+ * its report has none.
6
+ */
7
+ /** True when update describes a different job than the report merged before it. */
8
+ export declare function startsNewJob(previous: Record<string, any> | undefined, update: Record<string, any>): boolean;
9
+ /** The previous job's progress fields to leave out when update starts a new job without reporting them. */
10
+ export declare function newJobResets(previous: Record<string, any> | undefined, update: Record<string, any>): string[];
11
+ /** previous merged with update, without the previous job's progress when update starts a new one (newJobResets). */
12
+ export declare function mergeBambuReport(previous: Record<string, any> | undefined, update: Record<string, any>): Record<string, any>;
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Merging Bambu MQTT reports. P1/A1 printers push only what changed, so a merged report keeps every field until the
3
+ * printer sends it again. A new job's first pushes can carry its name and layer count before its layer number, and the
4
+ * previous job's last layer then read against the new total ("315/150"). Until the new job reports its own progress,
5
+ * its report has none.
6
+ */
7
+ /**
8
+ * Fields that name the job a report describes. The layer count is not one: a running job's count can be revised, and a
9
+ * different job differs in its name, file or task id.
10
+ */
11
+ const JOB_FIELDS = ["subtask_name", "gcode_file", "task_id"];
12
+ /** A new job prepares (PREPARE, SLICING) after any end; RUNNING straight after FAILED is that job resuming. */
13
+ const PREPARING = new Set(["PREPARE", "SLICING"]);
14
+ const DONE = new Set(["FINISH", "IDLE"]);
15
+ /** The previous job's progress, left out of a new job's report until the printer reports the new job's own. */
16
+ const JOB_PROGRESS = ["layer_num", "mc_percent", "mc_remaining_time"];
17
+ /** A job field's value, or undefined for a placeholder: empty, or 0 (LAN prints report task_id "0"). */
18
+ function named(value) {
19
+ const text = value === undefined || value === null ? "" : String(value).trim();
20
+ return text === "" || text === "0" ? undefined : text;
21
+ }
22
+ /** True when update describes a different job than the report merged before it. */
23
+ export function startsNewJob(previous, update) {
24
+ if (!previous)
25
+ return false;
26
+ for (const field of JOB_FIELDS) {
27
+ const before = named(previous[field]), after = named(update[field]);
28
+ if (before !== undefined && after !== undefined && before !== after)
29
+ return true;
30
+ }
31
+ const before = String(previous.gcode_state), after = String(update.gcode_state);
32
+ return (DONE.has(before) || before === "FAILED") && PREPARING.has(after) || DONE.has(before) && after === "RUNNING";
33
+ }
34
+ /** The previous job's progress fields to leave out when update starts a new job without reporting them. */
35
+ export function newJobResets(previous, update) {
36
+ if (!startsNewJob(previous, update))
37
+ return [];
38
+ return JOB_PROGRESS.filter(field => update[field] === undefined && previous?.[field] !== undefined);
39
+ }
40
+ /** previous merged with update, without the previous job's progress when update starts a new one (newJobResets). */
41
+ export function mergeBambuReport(previous, update) {
42
+ const merged = { ...previous, ...update };
43
+ for (const field of newJobResets(previous, update))
44
+ delete merged[field];
45
+ return merged;
46
+ }
@@ -27,6 +27,12 @@ export declare const MACHINE_LIMITS: Readonly<Record<string, {
27
27
  * (VIRTUAL_TRAY_DEPUTY_ID). The single-nozzle H2S is deliberately absent. */
28
28
  export declare const DUAL_NOZZLE_MODELS: ReadonlySet<string>;
29
29
  export declare function isDualNozzleModel(model: unknown): boolean;
30
+ /** File models a printer accepts besides its own, keyed by the printer's observed model.
31
+ * A P1P with the enclosure upgrade kit still reports itself as a P1P, while its jobs are sliced with the P1S
32
+ * preset. Bambu Studio sends those jobs: resources/printers/C11.json (P1P) lists C12 (P1S) in compatible_machine.
33
+ * The two models have identical MACHINE_LIMITS, and the file is still checked against the printer's own limits. */
34
+ export declare const ACCEPTED_FILE_MODELS: Readonly<Record<string, ReadonlySet<string>>>;
35
+ export declare function fileModelFitsPrinter(fileModel: string, printerModel: string): boolean;
30
36
  export declare function normalizeModel(value: unknown): string | undefined;
31
37
  export declare function normalizeMaterial(value: unknown): string | undefined;
32
38
  export declare function validateTemperature(component: 'nozzle' | 'bed' | 'chamber', value: unknown, model: string, materials?: string[]): number;