bambu-printer-mcp 1.1.26 → 1.1.27

package/README.md

@@ -878,6 +878,24 @@ To stop drying:
 }
 ```
 
+#### inspect_print_file
+
+Inspect a prepared sliced 3MF or textual G-code file offline before deciding what to export or print. This tool copies the file into a private read-only snapshot and reuses the same archive, selected-plate, model/nozzle/material and temperature checks used by print preflight. It never contacts a printer or auto-slices an unsliced project.
+
+```json
+{
+  "file_path": "/path/to/bracket.gcode.3mf",
+  "bambu_model": "p1s",
+  "plate_index": 0,
+  "nozzle_diameters": [0.4],
+  "bed_type": "textured_plate"
+}
+```
+
+`file_path` and explicit `bambu_model` are required; the model is never inferred from configuration. `plate_index` is zero-based and defaults to 0. Nozzle/bed checks are optional comparisons against file declarations, not observations of installed hardware. Only these five argument names are accepted; credentials, host and executable/bridge overrides are not part of this tool.
+
+The generic result has `receipt_version: "1"`, `evidence: "file-only"`, `dispatch_authorized: false`, `artifact` (`sha256`, `byte_length`, `file_format`), the requested `selection`, and the original `inspection` including declared model, nozzles, materials/used filament positions, internal plate path and checked temperature peaks. Hash and byte length identify the exact inspected snapshot; a consumer must compare them with its own artifact and selected plate. The temporary snapshot is removed, and its path is not a dispatch capability. The receipt does not prove printer readiness, physical material/nozzle contents, fit, full motion simulation or permission to print. Actual print routes still independently inspect the dispatched snapshot and require fresh hardware state and human preflight.
+
 #### print_3mf
 
 The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `.gcode.3mf` exported from FULU OrcaSlicer-bambulab, OrcaSlicer, or Bambu Studio** — see [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md). This tool handles the complete workflow:

package/dist/index.js

@@ -2377,6 +2377,23 @@ class BambuPrinterMCPServer {
                             required: ["action", "ams_id"]
                         }
                     },
+                    {
+                        name: "inspect_print_file",
+                        description: "Inspect an exact private snapshot of a prepared sliced 3MF or textual G-code file and selected plate without contacting a printer. Returns versioned file-only evidence; no printer readiness or permission to dispatch is established. Does not auto-slice.",
+                        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+                        inputSchema: {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                file_path: { type: "string", minLength: 1, description: "Local prepared .3mf or textual .gcode artifact to inspect; checksum-only and unsliced projects reject." },
+                                bambu_model: { type: "string", enum: [...VALID_BAMBU_MODELS], description: "Explicit file-inspection target model; never inferred from environment or live state." },
+                                plate_index: { type: "integer", minimum: 0, description: "Zero-based selected plate; defaults to 0. Raw G-code only supports 0." },
+                                nozzle_diameters: { type: "array", minItems: 1, maxItems: 2, items: { type: "number", enum: [0.2, 0.4, 0.6, 0.8] }, description: "Optional requested nozzle diameters to compare with file declarations; this does not observe installed hardware." },
+                                bed_type: { type: "string", enum: [...VALID_BED_TYPES], description: "Optional declared bed type to compare with file metadata." },
+                            },
+                            required: ["file_path", "bambu_model"],
+                        },
+                    },
                     {
                         name: "print_3mf",
                         description: "Print a 3MF file on a Bambu Lab printer. Auto-slices if the 3MF has no gcode. IMPORTANT: bambu_model must be specified to ensure safe printer operation.",
@@ -2613,6 +2630,42 @@ class BambuPrinterMCPServer {
             try {
                 let result;
                 switch (name) {
+                    case "inspect_print_file": {
+                        const allowed = new Set(["file_path", "bambu_model", "plate_index", "nozzle_diameters", "bed_type"]);
+                        if (!args || Object.keys(args).some(key => !allowed.has(key)))
+                            throw new Error("inspect_print_file accepts only file/model/plate/nozzle/bed arguments.");
+                        if (typeof args.file_path !== "string" || !args.file_path.trim() || args.file_path.includes("\0"))
+                            throw new Error("file_path must name a local prepared artifact.");
+                        if (typeof args.bambu_model !== "string" || !args.bambu_model.trim())
+                            throw new Error("An explicit bambu_model is required for file inspection.");
+                        const model = validateBambuModel(args.bambu_model);
+                        const plateIndex = args.plate_index === undefined ? 0 : args.plate_index;
+                        if (typeof plateIndex !== "number" || !Number.isSafeInteger(plateIndex) || plateIndex < 0)
+                            throw new Error("plate_index must be a nonnegative safe integer.");
+                        if (args.nozzle_diameters !== undefined && (!Array.isArray(args.nozzle_diameters) || args.nozzle_diameters.some(value => typeof value !== "number")))
+                            throw new Error("nozzle_diameters must be numeric sizes.");
+                        const nozzles = requestedPrintNozzles(args);
+                        if (args.bed_type !== undefined && (typeof args.bed_type !== "string" || !args.bed_type.trim()))
+                            throw new Error("bed_type must be a supported plate type.");
+                        const bedType = args.bed_type === undefined ? undefined : resolveBedType(args.bed_type);
+                        if (extra.signal.aborted)
+                            throw new Error("File inspection cancelled.");
+                        result = await withPrintSnapshot(args.file_path, async (snapshot) => {
+                            const inspection = await inspectPrintFile(snapshot, { model, nozzleDiameters: nozzles, plateIndex, bedType });
+                            if (extra.signal.aborted)
+                                throw new Error("File inspection cancelled.");
+                            const byteLength = (await fs.promises.stat(snapshot)).size;
+                            return {
+                                receipt_version: "1",
+                                evidence: "file-only",
+                                dispatch_authorized: false,
+                                artifact: { sha256: inspection.sha256, byte_length: byteLength, file_format: path.extname(snapshot).toLowerCase() === ".3mf" ? "3mf" : "gcode" },
+                                selection: { bambu_model: model, plate_index: plateIndex, ...(nozzles === undefined ? {} : { nozzle_diameters: nozzles }), ...(bedType === undefined ? {} : { bed_type: bedType }) },
+                                inspection,
+                            };
+                        });
+                        break;
+                    }
                     case "get_printer_status":
                         result = await this.bambu.getStatus(host, bambuSerial, bambuToken);
                         break;

package/dist/safety/print-file.js

@@ -372,10 +372,14 @@ export async function inspectPrintFile(filePath, options) {
             if (/[{}\[\]#]/.test(line))
                 fail('unresolved dynamic command syntax');
             if (/^SYNC(?=$|\s)/i.test(line)) {
-                // H2D change_filament_gcode emits SYNC T{ceil(flush_length / 125) * 5}.
-                // T is a synchronization duration here, not a nozzle temperature. The
-                // vendor template establishes no independent maximum duration.
+                // Vendor SYNC T is a duration, not a heater target. X2D and P2S
+                // startup templates additionally emit R0; no other R form is supported.
                 const args = parameters(line.slice(4));
+                if (args.has('R')) {
+                    if (!['x2d', 'p2s'].includes(model) || args.get('R') !== 0)
+                        fail('unsupported SYNC reset parameters');
+                    args.delete('R');
+                }
                 if (args.size !== 1 || !args.has('T') || !Number.isFinite(args.get('T')) || args.get('T') < 0)
                     fail('unsupported SYNC duration parameters');
                 commandCount++;

package/dist/slicer/profile-files.d.ts

@@ -0,0 +1,2 @@
+/** Discover vendor subfolders without following links into another profile tree. */
+export declare function profileJsonFiles(directory: string): string[];

package/dist/slicer/profile-files.js

@@ -0,0 +1,24 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+/** Discover vendor subfolders without following links into another profile tree. */
+export function profileJsonFiles(directory) {
+    let entries;
+    try {
+        if (lstatSync(directory).isSymbolicLink())
+            return [];
+        entries = readdirSync(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    const files = entries.filter(entry => entry.isFile() && entry.name.endsWith('.json'))
+        .map(entry => path.join(directory, entry.name));
+    for (const entry of entries) {
+        if (entry.isDirectory())
+            files.push(...profileJsonFiles(path.join(directory, entry.name)));
+    }
+    return files;
+}

package/dist/slicer/profile-flatten.js

@@ -27,6 +27,7 @@ import fs from "node:fs/promises";
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { profileJsonFiles } from './profile-files.js';
 /* -------------------------------------------------------------------------- */
 /* Indexing                                                                    */
 /* -------------------------------------------------------------------------- */
@@ -48,19 +49,7 @@ async function buildNameIndex(profilesRoot, vendor, userProfileRoots = []) {
         ...userProfileRoots.flatMap(root => ['process', 'filament'].map(sub => path.join(root, sub))),
     ];
     for (const dir of directories) {
-        let entries;
-        try {
-            entries = await fs.readdir(dir);
-        }
-        catch {
-            // Vendor or subdir missing -- skip silently; flatten will fail later
-            // with a precise "name not found" error.
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.endsWith(".json"))
-                continue;
-            const filePath = path.join(dir, entry);
+        for (const filePath of profileJsonFiles(dir)) {
             let raw;
             try {
                 raw = await fs.readFile(filePath, "utf8");

package/dist/stl/stl-manipulator.js

@@ -10,6 +10,7 @@ import { EventEmitter } from 'events';
 import * as crypto from 'crypto';
 import { execFile } from 'child_process';
 import { flattenForCli, detectProfilesRoot, resolveBblMachineProfile } from '../slicer/profile-flatten.js';
+import { profileJsonFiles } from '../slicer/profile-files.js';
 const readFileAsync = promisify(fs.readFile);
 const writeFileAsync = promisify(fs.writeFile);
 const BAMBU_PROFILE_ROOTS = [
@@ -134,10 +135,10 @@ export class STLManipulator extends EventEmitter {
             return undefined;
         }
         for (const root of roots) {
-            const candidate = path.join(root, category, `${profileName}.json`);
-            if (fs.existsSync(candidate)) {
+            const candidate = profileJsonFiles(path.join(root, category))
+                .find(file => path.basename(file) === `${profileName}.json`);
+            if (candidate)
                 return candidate;
-            }
         }
         return undefined;
     }
@@ -148,11 +149,7 @@ export class STLManipulator extends EventEmitter {
             if (!fs.existsSync(filamentDir)) {
                 continue;
             }
-            for (const entry of fs.readdirSync(filamentDir)) {
-                if (!entry.endsWith('.json')) {
-                    continue;
-                }
-                const filePath = path.join(filamentDir, entry);
+            for (const filePath of profileJsonFiles(filamentDir)) {
                 try {
                     const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
                     const filamentId = typeof parsed?.filament_id === 'string' ? parsed.filament_id.trim() : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bambu-printer-mcp",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "MCP server for Bambu Lab 3D printers with STL manipulation, slicing, and print management",
   "main": "dist/index.js",
   "repository": {

package/src/index.ts

@@ -2900,6 +2900,23 @@ class BambuPrinterMCPServer {
               required: ["action", "ams_id"]
             }
           },
+          {
+            name: "inspect_print_file",
+            description: "Inspect an exact private snapshot of a prepared sliced 3MF or textual G-code file and selected plate without contacting a printer. Returns versioned file-only evidence; no printer readiness or permission to dispatch is established. Does not auto-slice.",
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            inputSchema: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                file_path: { type: "string", minLength: 1, description: "Local prepared .3mf or textual .gcode artifact to inspect; checksum-only and unsliced projects reject." },
+                bambu_model: { type: "string", enum: [...VALID_BAMBU_MODELS], description: "Explicit file-inspection target model; never inferred from environment or live state." },
+                plate_index: { type: "integer", minimum: 0, description: "Zero-based selected plate; defaults to 0. Raw G-code only supports 0." },
+                nozzle_diameters: { type: "array", minItems: 1, maxItems: 2, items: { type: "number", enum: [0.2, 0.4, 0.6, 0.8] }, description: "Optional requested nozzle diameters to compare with file declarations; this does not observe installed hardware." },
+                bed_type: { type: "string", enum: [...VALID_BED_TYPES], description: "Optional declared bed type to compare with file metadata." },
+              },
+              required: ["file_path", "bambu_model"],
+            },
+          },
           {
             name: "print_3mf",
             description: "Print a 3MF file on a Bambu Lab printer. Auto-slices if the 3MF has no gcode. IMPORTANT: bambu_model must be specified to ensure safe printer operation.",
@@ -3147,6 +3164,34 @@ class BambuPrinterMCPServer {
         let result;
 
         switch (name) {
+          case "inspect_print_file": {
+            const allowed = new Set(["file_path", "bambu_model", "plate_index", "nozzle_diameters", "bed_type"]);
+            if (!args || Object.keys(args).some(key => !allowed.has(key))) throw new Error("inspect_print_file accepts only file/model/plate/nozzle/bed arguments.");
+            if (typeof args.file_path !== "string" || !args.file_path.trim() || args.file_path.includes("\0")) throw new Error("file_path must name a local prepared artifact.");
+            if (typeof args.bambu_model !== "string" || !args.bambu_model.trim()) throw new Error("An explicit bambu_model is required for file inspection.");
+            const model = validateBambuModel(args.bambu_model);
+            const plateIndex = args.plate_index === undefined ? 0 : args.plate_index;
+            if (typeof plateIndex !== "number" || !Number.isSafeInteger(plateIndex) || plateIndex < 0) throw new Error("plate_index must be a nonnegative safe integer.");
+            if (args.nozzle_diameters !== undefined && (!Array.isArray(args.nozzle_diameters) || args.nozzle_diameters.some(value => typeof value !== "number"))) throw new Error("nozzle_diameters must be numeric sizes.");
+            const nozzles = requestedPrintNozzles(args);
+            if (args.bed_type !== undefined && (typeof args.bed_type !== "string" || !args.bed_type.trim())) throw new Error("bed_type must be a supported plate type.");
+            const bedType = args.bed_type === undefined ? undefined : resolveBedType(args.bed_type);
+            if (extra.signal.aborted) throw new Error("File inspection cancelled.");
+            result = await withPrintSnapshot(args.file_path, async snapshot => {
+              const inspection = await inspectPrintFile(snapshot, { model, nozzleDiameters: nozzles, plateIndex, bedType });
+              if (extra.signal.aborted) throw new Error("File inspection cancelled.");
+              const byteLength = (await fs.promises.stat(snapshot)).size;
+              return {
+                receipt_version: "1",
+                evidence: "file-only",
+                dispatch_authorized: false,
+                artifact: { sha256: inspection.sha256, byte_length: byteLength, file_format: path.extname(snapshot).toLowerCase() === ".3mf" ? "3mf" : "gcode" },
+                selection: { bambu_model: model, plate_index: plateIndex, ...(nozzles === undefined ? {} : { nozzle_diameters: nozzles }), ...(bedType === undefined ? {} : { bed_type: bedType }) },
+                inspection,
+              };
+            });
+            break;
+          }
           case "get_printer_status":
             result = await this.bambu.getStatus(host, bambuSerial, bambuToken);
             break;

package/src/safety/print-file.ts

@@ -278,10 +278,13 @@ export async function inspectPrintFile(filePath: string, options: {model:string;
       line=line.replace(/^N\d+\s*/i,'').replace(/\*\d+\s*$/,'');
       if(/[{}\[\]#]/.test(line)) fail('unresolved dynamic command syntax');
       if(/^SYNC(?=$|\s)/i.test(line)) {
-        // H2D change_filament_gcode emits SYNC T{ceil(flush_length / 125) * 5}.
-        // T is a synchronization duration here, not a nozzle temperature. The
-        // vendor template establishes no independent maximum duration.
+        // Vendor SYNC T is a duration, not a heater target. X2D and P2S
+        // startup templates additionally emit R0; no other R form is supported.
         const args=parameters(line.slice(4));
+        if(args.has('R')) {
+          if(!['x2d','p2s'].includes(model) || args.get('R')!==0) fail('unsupported SYNC reset parameters');
+          args.delete('R');
+        }
         if(args.size!==1 || !args.has('T') || !Number.isFinite(args.get('T')) || args.get('T')!<0) fail('unsupported SYNC duration parameters');
         commandCount++;continue;
       }

package/src/slicer/profile-files.ts

@@ -0,0 +1,21 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+/** Discover vendor subfolders without following links into another profile tree. */
+export function profileJsonFiles(directory: string): string[] {
+  let entries;
+  try {
+    if (lstatSync(directory).isSymbolicLink()) return [];
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const files = entries.filter(entry => entry.isFile() && entry.name.endsWith('.json'))
+    .map(entry => path.join(directory, entry.name));
+  for (const entry of entries) {
+    if (entry.isDirectory()) files.push(...profileJsonFiles(path.join(directory, entry.name)));
+  }
+  return files;
+}

package/src/slicer/profile-flatten.ts

@@ -28,6 +28,7 @@ import fs from "node:fs/promises";
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { profileJsonFiles } from './profile-files.js';
 
 export type ProfileKind = "machine" | "process" | "filament";
 
@@ -125,17 +126,7 @@ async function buildNameIndex(
     ...userProfileRoots.flatMap(root => ['process', 'filament'].map(sub => path.join(root, sub))),
   ];
   for (const dir of directories) {
-    let entries: string[];
-    try {
-      entries = await fs.readdir(dir);
-    } catch {
-      // Vendor or subdir missing -- skip silently; flatten will fail later
-      // with a precise "name not found" error.
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.endsWith(".json")) continue;
-      const filePath = path.join(dir, entry);
+    for (const filePath of profileJsonFiles(dir)) {
       let raw: string;
       try {
         raw = await fs.readFile(filePath, "utf8");

package/src/stl/stl-manipulator.ts

@@ -10,6 +10,7 @@ import { EventEmitter } from 'events';
 import * as crypto from 'crypto';
 import { execFile } from 'child_process';
 import { flattenForCli, detectProfilesRoot, resolveBblMachineProfile } from '../slicer/profile-flatten.js';
+import { profileJsonFiles } from '../slicer/profile-files.js';
 
 const readFileAsync = promisify(fs.readFile);
 const writeFileAsync = promisify(fs.writeFile);
@@ -232,10 +233,9 @@ export class STLManipulator extends EventEmitter {
     }
 
     for (const root of roots) {
-      const candidate = path.join(root, category, `${profileName}.json`);
-      if (fs.existsSync(candidate)) {
-        return candidate;
-      }
+      const candidate = profileJsonFiles(path.join(root, category))
+        .find(file => path.basename(file) === `${profileName}.json`);
+      if (candidate) return candidate;
     }
 
     return undefined;
@@ -250,12 +250,7 @@ export class STLManipulator extends EventEmitter {
         continue;
       }
 
-      for (const entry of fs.readdirSync(filamentDir)) {
-        if (!entry.endsWith('.json')) {
-          continue;
-        }
-
-        const filePath = path.join(filamentDir, entry);
+      for (const filePath of profileJsonFiles(filamentDir)) {
         try {
           const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
           const filamentId = typeof parsed?.filament_id === 'string' ? parsed.filament_id.trim() : '';