mcp-3d-printer-server 1.2.25 → 1.2.26

package/dist/printers/bambu-filaments.d.ts

@@ -0,0 +1,68 @@
+import type { FilamentSlot } from "../counterpart/contract.js";
+export declare const FILAMENT_MODEL_CODES: Record<string, string>;
+type ProfileResolution = "exact-model-nozzle" | "model" | "generic" | "unresolved";
+export type PrinterFilamentTray = {
+    ams_id: number | null;
+    tray_id: number | null;
+    slot: number | null;
+    state: number;
+    loaded: boolean;
+    tray_info_idx: string | null;
+    tray_type: string | null;
+    tray_sub_brands: string | null;
+    tray_color: string | null;
+    remain_percent: number | null;
+    nozzle_temp_min: number | null;
+    nozzle_temp_max: number | null;
+    resolved_base_profile_name: string | null;
+    resolved_profile_path: string | null;
+    profile_resolution: ProfileResolution;
+    match_confidence: "high" | "medium" | "low" | "none";
+    display_name: string;
+    profile_candidates: string[];
+};
+export type PrinterFilamentInventory = {
+    current_slot: number | null;
+    current_source: "ams" | "external" | null;
+    summary: {
+        loaded_slots: number;
+        resolved_profile_slots: number;
+        unresolved_loaded_slots: number;
+        empty_slots: number;
+        current_slot: number | null;
+        current_source: "ams" | "external" | null;
+        recommended_slot: number | null;
+        recommended_reason: string | null;
+    };
+    trays: PrinterFilamentTray[];
+    recommended: {
+        slot: number | null;
+        tray_info_idx: string | null;
+        tray_type: string | null;
+        resolved_profile_path: string | null;
+        load_filaments: string | null;
+        reason: string;
+    } | null;
+    load_filaments_all: string | null;
+};
+export interface FilamentProfileSource {
+    slicerPath?: string;
+    slicerType?: string;
+}
+export declare function clearBambuFilamentProfileCache(): void;
+/**
+ * Lowercase 6-character RGB, dropping a leading "#" and any alpha. Bambu mixes
+ * #RRGGBB (3MF project settings) and RRGGBBAA (AMS reports); RGB is the key.
+ */
+export declare function normalizeRgbColor(color: string | null | undefined): string | null;
+/** bambu-printer-mcp's inventory: AMS trays (absolute slot = ams_id * 4 + tray_id), summary and recommendation. */
+export declare function normalizePrinterFilamentInventory(status: any, source: FilamentProfileSource, bambuModel?: string, nozzleDiameter?: string): PrinterFilamentInventory;
+/**
+ * The external spool(s) the printer reports: vir_slot entries 254/255 on
+ * dual-nozzle printers, else vt_tray as 254. A spool is loaded once the printer
+ * knows its type (tray_type), as Bambu Studio shows it.
+ */
+export declare function externalSpools(status: any, source: FilamentProfileSource, bambuModel?: string, nozzleDiameter?: string): PrinterFilamentTray[];
+/** counterpart/1 slots: every AMS tray (id "<absolute slot>") and external spool ("254"/"255"); no nulls. */
+export declare function counterpartSlots(inventory: PrinterFilamentInventory, external: PrinterFilamentTray[]): FilamentSlot[];
+export {};

package/dist/printers/bambu-filaments.js

@@ -0,0 +1,262 @@
+/**
+ * Bambu AMS and external-spool inventory, ported from bambu-printer-mcp's
+ * get_printer_filaments (normalizePrinterFilamentInventory). `trays` and the
+ * fields beside it are bambu-printer-mcp's result, field for field, so a
+ * client reads either server alike; `slots` is the counterpart/1 contract,
+ * which also lists the external spool(s) the printer reports (vt_tray, and
+ * vir_slot on dual-nozzle printers).
+ *
+ * Profiles resolve by the tray's tray_info_idx (Bambu filament_id) against
+ * the slicer's BBL/filament profiles, preferring the model-and-nozzle preset.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { detectProfilesRoot } from "../slicer/profile-flatten.js";
+export const FILAMENT_MODEL_CODES = {
+    p1s: "P1S",
+    p1p: "P1P",
+    p2s: "P2S",
+    x1c: "X1C",
+    x1e: "X1E",
+    a1: "A1",
+    a1mini: "A1M",
+    h2d: "H2D",
+    h2dpro: "H2DP",
+    h2s: "H2S",
+    h2c: "H2C",
+    x2d: "X2D",
+};
+const indexCache = new Map();
+function buildFilamentProfileIndex(source) {
+    const byName = new Map();
+    const baseNameByFilamentId = new Map();
+    let filamentProfileDir;
+    try {
+        const slicerType = source.slicerType === "bambustudio" ? "bambustudio" : "orcaslicer";
+        filamentProfileDir = path.join(detectProfilesRoot(source.slicerPath, slicerType), "BBL", "filament");
+    }
+    catch {
+        // Profile suggestions are optional; invalid slicer configuration must not hide AMS inventory.
+        return { byName, baseNameByFilamentId };
+    }
+    let profileEntries;
+    try {
+        profileEntries = fs.readdirSync(filamentProfileDir);
+    }
+    catch {
+        return { byName, baseNameByFilamentId };
+    }
+    for (const entry of profileEntries) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const filePath = path.join(filamentProfileDir, entry);
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            const name = typeof parsed?.name === "string" ? parsed.name.trim() : "";
+            const filamentId = typeof parsed?.filament_id === "string" ? parsed.filament_id.trim() : "";
+            if (name)
+                byName.set(name, filePath);
+            if (name && filamentId)
+                baseNameByFilamentId.set(filamentId, name);
+        }
+        catch {
+            // Ignore malformed or non-profile JSON files.
+        }
+    }
+    return { byName, baseNameByFilamentId };
+}
+function filamentProfileIndex(source) {
+    const key = `${process.env.BAMBU_PROFILES_ROOT ?? ""}\n${source.slicerType ?? ""}\n${source.slicerPath ?? ""}`;
+    let index = indexCache.get(key);
+    if (!index) {
+        index = buildFilamentProfileIndex(source);
+        indexCache.set(key, index);
+    }
+    return index;
+}
+export function clearBambuFilamentProfileCache() {
+    indexCache.clear();
+}
+function resolveFilamentProfileCandidates(trayInfoIdx, source, bambuModel, nozzleDiameter) {
+    const index = filamentProfileIndex(source);
+    const baseName = index.baseNameByFilamentId.get(trayInfoIdx) || null;
+    if (!baseName)
+        return { baseName: null, paths: [], resolution: "unresolved" };
+    const bareName = baseName.replace(/\s*@base$/, "");
+    const modelCode = bambuModel ? FILAMENT_MODEL_CODES[bambuModel] : undefined;
+    const candidateNames = [];
+    if (modelCode && nozzleDiameter)
+        candidateNames.push(`${bareName} @BBL ${modelCode} ${nozzleDiameter} nozzle`);
+    if (modelCode)
+        candidateNames.push(`${bareName} @BBL ${modelCode}`);
+    candidateNames.push(bareName, baseName);
+    const resolvedPaths = [];
+    let resolution = "unresolved";
+    for (const [candidateIndex, candidateName] of candidateNames.entries()) {
+        const candidatePath = index.byName.get(candidateName);
+        if (!candidatePath || resolvedPaths.includes(candidatePath))
+            continue;
+        resolvedPaths.push(candidatePath);
+        if (resolution === "unresolved") {
+            if (candidateIndex === 0 && modelCode && nozzleDiameter) {
+                resolution = "exact-model-nozzle";
+            }
+            else if ((candidateIndex === 0 && modelCode && !nozzleDiameter) ||
+                (candidateIndex === 1 && modelCode && nozzleDiameter)) {
+                resolution = "model";
+            }
+            else {
+                resolution = "generic";
+            }
+        }
+    }
+    return { baseName, paths: resolvedPaths, resolution };
+}
+function parseIntegerOrNull(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    const parsed = Number.parseInt(String(value), 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Lowercase 6-character RGB, dropping a leading "#" and any alpha. Bambu mixes
+ * #RRGGBB (3MF project settings) and RRGGBBAA (AMS reports); RGB is the key.
+ */
+export function normalizeRgbColor(color) {
+    if (!color)
+        return null;
+    const hex = color.replace(/^#/, "").toLowerCase();
+    if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/.test(hex))
+        return null;
+    return hex.slice(0, 6);
+}
+function trayEntry(tray, ids, source, bambuModel, nozzleDiameter) {
+    const trayInfoIdx = typeof tray?.tray_info_idx === "string" ? tray.tray_info_idx : null;
+    const profileResolution = trayInfoIdx
+        ? resolveFilamentProfileCandidates(trayInfoIdx, source, bambuModel, nozzleDiameter)
+        : { baseName: null, paths: [], resolution: "unresolved" };
+    const matchConfidence = profileResolution.resolution === "exact-model-nozzle" ? "high" :
+        profileResolution.resolution === "model" ? "medium" :
+            profileResolution.resolution === "generic" ? "low" :
+                "none";
+    const trayType = typeof tray?.tray_type === "string" ? tray.tray_type : null;
+    const traySubBrands = typeof tray?.tray_sub_brands === "string" ? tray.tray_sub_brands : null;
+    const trayColor = typeof tray?.tray_color === "string" ? tray.tray_color : null;
+    const displayParts = [
+        traySubBrands && traySubBrands !== trayType ? traySubBrands : null,
+        trayType,
+        trayColor ? `#${normalizeRgbColor(trayColor) ?? trayColor.replace(/^#/, "").slice(0, 6)}` : null,
+    ].filter(Boolean);
+    return {
+        ams_id: ids.amsId,
+        tray_id: ids.trayId,
+        slot: ids.slot,
+        state: ids.state,
+        loaded: ids.state !== 0 && Boolean(trayInfoIdx),
+        tray_info_idx: trayInfoIdx,
+        tray_type: trayType,
+        tray_sub_brands: traySubBrands,
+        tray_color: trayColor,
+        remain_percent: typeof tray?.remain === "number" && tray.remain >= 0 ? tray.remain : null,
+        nozzle_temp_min: parseIntegerOrNull(tray?.nozzle_temp_min),
+        nozzle_temp_max: parseIntegerOrNull(tray?.nozzle_temp_max),
+        resolved_base_profile_name: profileResolution.baseName,
+        resolved_profile_path: profileResolution.paths[0] || null,
+        profile_resolution: profileResolution.resolution,
+        match_confidence: matchConfidence,
+        display_name: displayParts.length > 0 ? displayParts.join(" ") : "empty/unknown",
+        profile_candidates: profileResolution.paths,
+    };
+}
+/** bambu-printer-mcp's inventory: AMS trays (absolute slot = ams_id * 4 + tray_id), summary and recommendation. */
+export function normalizePrinterFilamentInventory(status, source, bambuModel, nozzleDiameter) {
+    const rawAms = status?.raw?.ams || status?.ams || {};
+    const trayNow = parseIntegerOrNull(rawAms?.tray_now);
+    const trays = [];
+    const amsArray = Array.isArray(rawAms?.ams) ? rawAms.ams : [];
+    for (const [amsIndex, amsUnit] of amsArray.entries()) {
+        const trayArray = Array.isArray(amsUnit?.tray) ? amsUnit.tray : [];
+        for (const [trayIndex, tray] of trayArray.entries()) {
+            const amsId = parseIntegerOrNull(amsUnit?.id) ?? amsIndex;
+            const trayId = parseIntegerOrNull(tray?.id) ?? trayIndex;
+            const slot = amsId !== null && trayId !== null ? amsId * 4 + trayId : null;
+            const state = parseIntegerOrNull(tray?.state) ?? 0;
+            trays.push(trayEntry(tray, { amsId, trayId, slot, state }, source, bambuModel, nozzleDiameter));
+        }
+    }
+    const loadedTrays = trays.filter((tray) => tray.loaded);
+    const recommendedTray = loadedTrays.find((tray) => tray.slot === trayNow && tray.resolved_profile_path) ||
+        loadedTrays.find((tray) => tray.resolved_profile_path) ||
+        null;
+    const recommendedReason = recommendedTray?.slot === trayNow
+        ? "current AMS slot with resolved slicer profile"
+        : recommendedTray
+            ? "first loaded AMS slot with resolved slicer profile"
+            : null;
+    const allProfilePaths = Array.from(new Set(loadedTrays.map((tray) => tray.resolved_profile_path).filter((candidate) => Boolean(candidate))));
+    const emptySlots = trays.filter((tray) => !tray.loaded).length;
+    const resolvedProfileSlots = loadedTrays.filter((tray) => tray.resolved_profile_path).length;
+    const currentSlot = trayNow !== null && trayNow >= 0 && trayNow < 254 ? trayNow : null;
+    const currentSource = trayNow === 254 ? "external" : currentSlot !== null ? "ams" : null;
+    return {
+        current_slot: currentSlot,
+        current_source: currentSource,
+        summary: {
+            loaded_slots: loadedTrays.length,
+            resolved_profile_slots: resolvedProfileSlots,
+            unresolved_loaded_slots: loadedTrays.length - resolvedProfileSlots,
+            empty_slots: emptySlots,
+            current_slot: currentSlot,
+            current_source: currentSource,
+            recommended_slot: recommendedTray?.slot ?? null,
+            recommended_reason: recommendedReason,
+        },
+        trays,
+        recommended: recommendedTray
+            ? {
+                slot: recommendedTray.slot,
+                tray_info_idx: recommendedTray.tray_info_idx,
+                tray_type: recommendedTray.tray_type,
+                resolved_profile_path: recommendedTray.resolved_profile_path,
+                load_filaments: recommendedTray.resolved_profile_path,
+                reason: recommendedReason ?? "resolved slicer profile",
+            }
+            : null,
+        load_filaments_all: allProfilePaths.length > 0 ? allProfilePaths.join(";") : null,
+    };
+}
+/**
+ * The external spool(s) the printer reports: vir_slot entries 254/255 on
+ * dual-nozzle printers, else vt_tray as 254. A spool is loaded once the printer
+ * knows its type (tray_type), as Bambu Studio shows it.
+ */
+export function externalSpools(status, source, bambuModel, nozzleDiameter) {
+    const raw = status?.raw ?? status ?? {};
+    const virtual = Array.isArray(raw?.vir_slot) ? raw.vir_slot : [];
+    const spools = virtual
+        .filter((slot) => [254, 255].includes(Number(slot?.id)))
+        .map((slot) => ({ slot: Number(slot.id), tray: slot }));
+    if (!spools.length && raw?.vt_tray && typeof raw.vt_tray === "object")
+        spools.push({ slot: 254, tray: raw.vt_tray });
+    return spools.map(({ slot, tray }) => {
+        const known = typeof tray?.tray_type === "string" && tray.tray_type.trim() !== "";
+        const entry = trayEntry(tray, { amsId: slot, trayId: 0, slot, state: known ? 1 : 0 }, source, bambuModel, nozzleDiameter);
+        return { ...entry, loaded: known };
+    });
+}
+/** counterpart/1 slots: every AMS tray (id "<absolute slot>") and external spool ("254"/"255"); no nulls. */
+export function counterpartSlots(inventory, external) {
+    return [...inventory.trays, ...external].flatMap((tray) => {
+        if (tray.slot === null || !tray.loaded)
+            return [];
+        const rgb = normalizeRgbColor(tray.tray_color);
+        return [{
+                id: String(tray.slot),
+                ...(tray.tray_type ? { material: tray.tray_type } : {}),
+                ...(rgb ? { color: `#${rgb.toUpperCase()}` } : {}),
+                ...(tray.display_name && tray.display_name !== "empty/unknown" ? { name: tray.display_name } : {}),
+                source: "printer",
+                ...(tray.resolved_profile_path ? { profile: tray.resolved_profile_path } : {}),
+            }];
+    });
+}

package/dist/printers/bambu.d.ts

@@ -1,5 +1,6 @@
 import { PrinterImplementation } from "../types.js";
 import { type PrintFileInspection } from "../safety/print-file.js";
+import { type PrinterStateRequirements } from "../safety/printer-state.js";
 import { type ConfirmHardware } from "../safety/confirmation.js";
 import { type ExpectedPeakTemperatures, type PrintSafetyOptions } from "../safety/expected-peaks.js";
 export interface BambuPrintOptionsInternal {
@@ -18,17 +19,62 @@ export interface BambuPrintOptionsInternal {
     timelapse?: boolean;
     /** Positional mapping: project filament position -> absolute AMS tray (254 = external spool). */
     amsMapping?: number[];
+    /** One absolute tray per used filament in plate order; expanded to the project-level mapping. */
+    amsSlots?: number[];
     md5?: string;
     expectedPeaks?: ExpectedPeakTemperatures;
 }
 export type BambuSafetyOptions = PrintSafetyOptions;
+/** The inspected bytes and limits of a started job, for the resume byte check and prompt. */
+export type CheckedFile = {
+    sha256: string;
+    /** A project's printed plate: its number and the SHA-256 of its Metadata/plate_<index>.gcode. */
+    plate?: {
+        index: number;
+        sha256: string;
+    };
+    model: string;
+    maxNozzleTemperature: number;
+    maxBedTemperature: number;
+    maxChamberTemperature: number;
+    materials: string[];
+};
+/** A route's own dispatch for a print control (FULU's BambuNetwork); undefined sends over LAN MQTT. */
+export type ControlDispatch = () => Promise<any>;
+export type ResumeDispatch = (assertActive: () => void, beforeDispatch: () => Promise<void>) => Promise<any>;
+/**
+ * Where each printer's resume record is kept so a restart of this server (a deploy, a crash, a reboot) during a
+ * pause can still resume the job it started: BAMBU_RESUME_STATE_DIR, else mcp-3d-printer-server/resume in the
+ * config home (bambu-printer-mcp keeps its own). Resume runs every check on a reloaded record: a fresh paused
+ * report naming this exact job, the re-read bytes or its unique name, and a person for an unverified file.
+ */
+export declare function defaultResumeStateDir(env?: NodeJS.ProcessEnv): string;
+/** What a resume needs to know about a started file (filePath, the inspected snapshot). */
+export declare function checkedFile(inspection: PrintFileInspection, filePath: string): Promise<CheckedFile>;
 export declare class BambuImplementation extends PrinterImplementation {
     private readonly confirm?;
     private printerStore;
-    constructor(apiClient: any, confirm?: ConfirmHardware | undefined);
-    confirmHardwareAction(message: string, physicalCheck?: boolean): Promise<void>;
-    private finishedJobIdentity;
-    confirmPrintPreflight(serial: string, status: any, inspection: PrintFileInspection): Promise<string | undefined>;
+    /**
+     * The job each printer may resume, keyed host and serial. Cancel, a report
+     * that it ended after it was seen running, or another job seen in its place
+     * retires it, so a later job that reuses the name is never resumed.
+     */
+    private readonly checkedJobs;
+    /** confirm: a person (MCP elicitation), asked only to resume a job whose file could not be re-read. */
+    constructor(apiClient: any, confirm?: ConfirmHardware | undefined, options?: {
+        resumeStateDir?: string;
+    });
+    /**
+     * Internal handoff from a successful inspected transport; never an MCP tool.
+     * uploadedHere is false for FULU's BambuNetwork routes, where Bambu's plug-in
+     * put the file on the printer at a path this server has not verified: a
+     * resume then re-reads it if it can and otherwise asks a person.
+     */
+    recordCheckedJob(host: string, serial: string, remotePath: string, requirements: PrinterStateRequirements, file: CheckedFile, uploadedHere?: boolean): void;
+    /** Retire a record that never started (the dispatch was refused or failed). */
+    forgetCheckedJob(host: string, serial: string, remotePath: string): void;
+    /** Feed one merged report to the resume record (the client store calls it for every report). */
+    observeReport(host: string, serial: string, raw: Record<string, any> | undefined): void;
     private getPrinter;
     /** Safety reads never use the display cache or configured-serial model inference. */
     getSafetyStatus(host: string, serial: string, token: string): Promise<any>;
@@ -38,6 +84,17 @@ export declare class BambuImplementation extends PrinterImplementation {
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     print3mf(host: string, serial: string, token: string, options: BambuPrintOptionsInternal): Promise<any>;
     private print3mfPrepared;
+    /**
+     * The project-level tray mapping for a checked print, built as
+     * bambu-printer-mcp builds it: position = project filament, value = absolute
+     * tray (0-15 AMS, 128+ AMS-HT, 254 external; 255 the right/main external
+     * spool on dual-nozzle printers, -1 unused). ams_mapping is taken as given;
+     * ams_slots supplies one tray per used filament and is expanded against the
+     * plate's filament_ids; use_ams:false maps every used filament to the
+     * external spool of its nozzle. Every used position must end up mapped.
+     * The wire form pads to the historical five entries.
+     */
+    private checkedAmsMapping;
     /**
      * A published print command is not proof the printer took it. Listen to the
      * reports the printer pushes anyway (no extra pushall polling on weak P1
@@ -45,8 +102,44 @@ export declare class BambuImplementation extends PrinterImplementation {
      * command; PREPARE/SLICING/RUNNING means it started. Attach before publishing.
      */
     private watchDispatch;
-    /** Stop is never gated or queued behind pending checked operations. */
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    /** A refused or unconfirmed-then-failed dispatch leaves no job to resume. */
+    private settleRecorded;
+    /**
+     * Stop is never gated or queued behind pending checked operations, and it
+     * retires the resume record. dispatch sends it over the route that printed
+     * (FULU's BambuNetwork); without one it goes over LAN MQTT.
+     */
+    cancelJob(host: string, port: string, apiKey: string, dispatch?: ControlDispatch): Promise<any>;
+    /** Pause is never gated. */
+    pauseJob(host: string, port: string, apiKey: string, dispatch?: ControlDispatch): Promise<{
+        status: string;
+        action: "pause";
+        message: string;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Resume reheats and moves the printer, so it is gated like a print start:
+     * only the job this server inspected and started, while a fresh report shows
+     * it paused, with its bytes re-read over FTPS and compared. Only a file that
+     * could not be re-read, and that this server did not upload itself, asks a
+     * person. The record must still be current at every check.
+     */
+    resumeJob(host: string, port: string, apiKey: string, dispatch?: ResumeDispatch): Promise<{
+        status: string;
+        action: "resume";
+        message: string;
+        jobName: string;
+        bytesVerified: boolean;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Re-read a started job's bytes over FTPS: the uploaded file, else the plate
+     * G-code the printer extracted from the project to print it. The first file
+     * that can be read decides; a mismatch is reported as changed.
+     */
+    private rereadJob;
+    /** SHA-256 of a printer file, streamed from an FTPS download into a private directory. */
+    private remoteSha256;
     setTemperature(host: string, port: string, apiKey: string, component: string, temperature: unknown, options?: BambuSafetyOptions): Promise<{
         status: string;
         message: string;