mcp-3d-printer-server 1.2.19 → 1.2.21

package/dist/counterpart/contract.d.ts

@@ -0,0 +1,395 @@
+export declare const COUNTERPART_CONTRACT = "counterpart/1";
+export declare const PRINTER_KINDS: readonly ["bambu", "octoprint", "klipper", "prusa", "duet", "repetier", "creality"];
+export type PrinterKind = (typeof PRINTER_KINDS)[number];
+export declare const PROGRESS_STATES: readonly ["idle", "preparing", "printing", "paused", "finished", "failed", "cancelled", "offline", "busy"];
+export type ProgressState = (typeof PROGRESS_STATES)[number];
+export declare const PROBLEM_SEVERITIES: readonly ["fatal", "error", "warning", "info"];
+export type ProblemSeverity = (typeof PROBLEM_SEVERITIES)[number];
+export type CameraCapability = "bambu-tcp" | "rtsp" | "http-snapshot" | "none";
+export type FilamentCapability = "ams" | "single" | "none";
+export interface CounterpartProblem {
+    code: string;
+    severity: ProblemSeverity;
+    message: string;
+    url?: string;
+}
+export interface HeaterReading {
+    actual: number;
+    target: number;
+}
+export interface CounterpartJob {
+    name: string;
+    id?: string;
+    progress?: number;
+    elapsedSec?: number;
+    remainingSec?: number;
+    layer?: number;
+    totalLayers?: number;
+    stage?: string;
+}
+export interface CounterpartProgress {
+    contract: typeof COUNTERPART_CONTRACT;
+    observedAt: string;
+    state: ProgressState;
+    job?: CounterpartJob;
+    temps?: {
+        nozzle?: HeaterReading;
+        bed?: HeaterReading;
+        chamber?: number;
+    };
+    activeFilament?: {
+        slot?: string;
+        material?: string;
+        color?: string;
+    };
+    problems: CounterpartProblem[];
+}
+export interface CounterpartCapabilities {
+    progress: boolean;
+    layers: boolean;
+    camera: CameraCapability;
+    filaments: FilamentCapability;
+    pause: boolean;
+    resume: boolean;
+    cancel: boolean;
+    print3mf: boolean;
+    gcode: boolean;
+}
+export interface PrinterIdentity {
+    model?: string;
+    serial?: string;
+    name?: string;
+}
+export interface CounterpartPrinterInfo {
+    contract: typeof COUNTERPART_CONTRACT;
+    server: {
+        name: string;
+        version: string;
+    };
+    printer: {
+        kind: PrinterKind;
+        host: string;
+    } & PrinterIdentity;
+    capabilities: CounterpartCapabilities;
+}
+export interface FilamentSlot {
+    id: "ext";
+    material?: string;
+    color?: string;
+    name?: string;
+    source: "spoolman" | "unknown";
+    /** Absolute path of the slicer filament profile for this material, as slice_stl's load_filaments takes it. */
+    profile?: string;
+}
+export interface CameraSnapshotResult {
+    status: "success";
+    format: "image/jpeg";
+    sizeBytes: number;
+    base64: string;
+    savedTo?: string;
+    capturedAt: string;
+    /** Where the frame came from, e.g. "octoprint-settings" or "env-override". */
+    source: string;
+}
+/** outputSchema for counterpart_printer_info (PRD §8.4). */
+export declare const PRINTER_INFO_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["contract", "server", "printer", "capabilities"];
+    readonly properties: {
+        readonly contract: {
+            readonly type: "string";
+            readonly const: "counterpart/1";
+        };
+        readonly server: {
+            readonly type: "object";
+            readonly required: readonly ["name", "version"];
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly version: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly printer: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "host"];
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly enum: readonly ["bambu", "octoprint", "klipper", "prusa", "duet", "repetier", "creality"];
+                };
+                readonly model: {
+                    readonly type: "string";
+                };
+                readonly serial: {
+                    readonly type: "string";
+                };
+                readonly host: {
+                    readonly type: "string";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly capabilities: {
+            readonly type: "object";
+            readonly required: readonly ["progress", "layers", "camera", "filaments", "pause", "resume", "cancel", "print3mf", "gcode"];
+            readonly properties: {
+                readonly progress: {
+                    readonly type: "boolean";
+                };
+                readonly layers: {
+                    readonly type: "boolean";
+                };
+                readonly camera: {
+                    readonly type: "string";
+                    readonly enum: readonly ["bambu-tcp", "rtsp", "http-snapshot", "none"];
+                };
+                readonly filaments: {
+                    readonly type: "string";
+                    readonly enum: readonly ["ams", "single", "none"];
+                };
+                readonly pause: {
+                    readonly type: "boolean";
+                };
+                readonly resume: {
+                    readonly type: "boolean";
+                };
+                readonly cancel: {
+                    readonly type: "boolean";
+                };
+                readonly print3mf: {
+                    readonly type: "boolean";
+                };
+                readonly gcode: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+    };
+};
+/** outputSchema for counterpart_print_progress (PRD §8.4). */
+export declare const PRINT_PROGRESS_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["contract", "observedAt", "state", "problems"];
+    readonly properties: {
+        readonly contract: {
+            readonly type: "string";
+            readonly const: "counterpart/1";
+        };
+        readonly observedAt: {
+            readonly type: "string";
+        };
+        readonly state: {
+            readonly type: "string";
+            readonly enum: readonly ["idle", "preparing", "printing", "paused", "finished", "failed", "cancelled", "offline", "busy"];
+        };
+        readonly job: {
+            readonly type: "object";
+            readonly required: readonly ["name"];
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly id: {
+                    readonly type: "string";
+                };
+                readonly progress: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 100;
+                };
+                readonly elapsedSec: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly remainingSec: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly layer: {
+                    readonly type: "number";
+                };
+                readonly totalLayers: {
+                    readonly type: "number";
+                };
+                readonly stage: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly temps: {
+            readonly type: "object";
+            readonly properties: {
+                readonly nozzle: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        actual: {
+                            type: string;
+                        };
+                        target: {
+                            type: string;
+                        };
+                    };
+                };
+                readonly bed: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        actual: {
+                            type: string;
+                        };
+                        target: {
+                            type: string;
+                        };
+                    };
+                };
+                readonly chamber: {
+                    readonly type: "number";
+                };
+            };
+        };
+        readonly activeFilament: {
+            readonly type: "object";
+            readonly properties: {
+                readonly slot: {
+                    readonly type: "string";
+                };
+                readonly material: {
+                    readonly type: "string";
+                };
+                readonly color: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly problems: {
+            readonly type: "array";
+            readonly items: {
+                type: string;
+                required: string[];
+                properties: {
+                    code: {
+                        type: string;
+                    };
+                    severity: {
+                        type: string;
+                        enum: ("error" | "fatal" | "warning" | "info")[];
+                    };
+                    message: {
+                        type: string;
+                    };
+                    url: {
+                        type: string;
+                    };
+                };
+            };
+        };
+    };
+};
+/** outputSchema for camera_snapshot; the result matches bambu-printer-mcp's plus capturedAt. */
+export declare const CAMERA_SNAPSHOT_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["status", "format", "sizeBytes", "base64", "capturedAt"];
+    readonly properties: {
+        readonly status: {
+            readonly type: "string";
+        };
+        readonly format: {
+            readonly type: "string";
+        };
+        readonly sizeBytes: {
+            readonly type: "number";
+        };
+        readonly base64: {
+            readonly type: "string";
+        };
+        readonly savedTo: {
+            readonly type: "string";
+        };
+        readonly capturedAt: {
+            readonly type: "string";
+        };
+        readonly source: {
+            readonly type: "string";
+        };
+    };
+};
+/** outputSchema for get_printer_filaments in this server: one external slot. */
+export declare const FILAMENTS_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["slots"];
+    readonly properties: {
+        readonly slots: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["id", "source"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly material: {
+                        readonly type: "string";
+                    };
+                    readonly color: {
+                        readonly type: "string";
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly source: {
+                        readonly type: "string";
+                        readonly enum: readonly ["spoolman", "unknown"];
+                    };
+                    readonly profile: {
+                        readonly type: "string";
+                        readonly description: "Absolute path of the installed slicer filament profile for this slot's material, which slice_stl accepts as load_filaments. Omitted when none resolves.";
+                    };
+                };
+            };
+        };
+    };
+};
+/** outputSchema for pause_print and resume_print. */
+export declare const CONTROL_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["status", "message"];
+    readonly properties: {
+        readonly status: {
+            readonly type: "string";
+        };
+        readonly message: {
+            readonly type: "string";
+        };
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["pause", "resume"];
+        };
+        readonly jobName: {
+            readonly type: "string";
+        };
+    };
+};
+export declare function finiteNumber(value: unknown): number | undefined;
+/** A percentage clamped to 0–100, rounded to 0.1. */
+export declare function percent(value: unknown): number | undefined;
+/** Non-negative whole seconds. */
+export declare function seconds(value: unknown): number | undefined;
+/** A positive integer layer count or index. */
+export declare function layerNumber(value: unknown): number | undefined;
+export declare function nonEmptyText(value: unknown): string | undefined;
+/** {actual, target} when the actual reading is finite; a missing target means off (0). */
+export declare function heaterReading(actual: unknown, target: unknown): HeaterReading | undefined;
+/**
+ * The job name the printer reports, reduced to its file name so it matches the
+ * uploaded `jobName` (Duet reports 0:/gcodes/x.gcode, Klipper gcodes-relative paths).
+ */
+export declare function remoteJobName(value: unknown): string | undefined;
+/** Remove undefined members recursively so results never carry null/undefined fields. */
+export declare function compact<T>(value: T): T;
+export declare function progressResult(observedAt: string, state: ProgressState, parts: Omit<Partial<CounterpartProgress>, "contract" | "observedAt" | "state">): CounterpartProgress;

package/dist/counterpart/contract.js

@@ -0,0 +1,220 @@
+/**
+ * The Counterpart tool contract (`counterpart/1`). bambu-printer-mcp and this
+ * server return the same shapes so one client can treat both alike. Optional
+ * fields are omitted, never null: JSON Schema `number` rejects null.
+ */
+import path from "node:path";
+export const COUNTERPART_CONTRACT = "counterpart/1";
+export const PRINTER_KINDS = ["bambu", "octoprint", "klipper", "prusa", "duet", "repetier", "creality"];
+export const PROGRESS_STATES = ["idle", "preparing", "printing", "paused", "finished", "failed", "cancelled", "offline", "busy"];
+export const PROBLEM_SEVERITIES = ["fatal", "error", "warning", "info"];
+const heater = {
+    type: "object",
+    required: ["actual", "target"],
+    properties: { actual: { type: "number" }, target: { type: "number" } },
+};
+const problem = {
+    type: "object",
+    required: ["code", "severity", "message"],
+    properties: {
+        code: { type: "string" },
+        severity: { type: "string", enum: [...PROBLEM_SEVERITIES] },
+        message: { type: "string" },
+        url: { type: "string" },
+    },
+};
+/** outputSchema for counterpart_printer_info (PRD §8.4). */
+export const PRINTER_INFO_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["contract", "server", "printer", "capabilities"],
+    properties: {
+        contract: { type: "string", const: COUNTERPART_CONTRACT },
+        server: {
+            type: "object",
+            required: ["name", "version"],
+            properties: { name: { type: "string" }, version: { type: "string" } },
+        },
+        printer: {
+            type: "object",
+            required: ["kind", "host"],
+            properties: {
+                kind: { type: "string", enum: [...PRINTER_KINDS] },
+                model: { type: "string" },
+                serial: { type: "string" },
+                host: { type: "string" },
+                name: { type: "string" },
+            },
+        },
+        capabilities: {
+            type: "object",
+            required: ["progress", "layers", "camera", "filaments", "pause", "resume", "cancel", "print3mf", "gcode"],
+            properties: {
+                progress: { type: "boolean" },
+                layers: { type: "boolean" },
+                camera: { type: "string", enum: ["bambu-tcp", "rtsp", "http-snapshot", "none"] },
+                filaments: { type: "string", enum: ["ams", "single", "none"] },
+                pause: { type: "boolean" },
+                resume: { type: "boolean" },
+                cancel: { type: "boolean" },
+                print3mf: { type: "boolean" },
+                gcode: { type: "boolean" },
+            },
+        },
+    },
+};
+/** outputSchema for counterpart_print_progress (PRD §8.4). */
+export const PRINT_PROGRESS_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["contract", "observedAt", "state", "problems"],
+    properties: {
+        contract: { type: "string", const: COUNTERPART_CONTRACT },
+        observedAt: { type: "string" },
+        state: { type: "string", enum: [...PROGRESS_STATES] },
+        job: {
+            type: "object",
+            required: ["name"],
+            properties: {
+                name: { type: "string" },
+                id: { type: "string" },
+                progress: { type: "number", minimum: 0, maximum: 100 },
+                elapsedSec: { type: "number", minimum: 0 },
+                remainingSec: { type: "number", minimum: 0 },
+                layer: { type: "number" },
+                totalLayers: { type: "number" },
+                stage: { type: "string" },
+            },
+        },
+        temps: {
+            type: "object",
+            properties: { nozzle: heater, bed: heater, chamber: { type: "number" } },
+        },
+        activeFilament: {
+            type: "object",
+            properties: { slot: { type: "string" }, material: { type: "string" }, color: { type: "string" } },
+        },
+        problems: { type: "array", items: problem },
+    },
+};
+/** outputSchema for camera_snapshot; the result matches bambu-printer-mcp's plus capturedAt. */
+export const CAMERA_SNAPSHOT_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["status", "format", "sizeBytes", "base64", "capturedAt"],
+    properties: {
+        status: { type: "string" },
+        format: { type: "string" },
+        sizeBytes: { type: "number" },
+        base64: { type: "string" },
+        savedTo: { type: "string" },
+        capturedAt: { type: "string" },
+        source: { type: "string" },
+    },
+};
+/** outputSchema for get_printer_filaments in this server: one external slot. */
+export const FILAMENTS_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["slots"],
+    properties: {
+        slots: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "source"],
+                properties: {
+                    id: { type: "string" },
+                    material: { type: "string" },
+                    color: { type: "string" },
+                    name: { type: "string" },
+                    source: { type: "string", enum: ["spoolman", "unknown"] },
+                    profile: {
+                        type: "string",
+                        description: "Absolute path of the installed slicer filament profile for this slot's material, which slice_stl accepts as load_filaments. Omitted when none resolves.",
+                    },
+                },
+            },
+        },
+    },
+};
+/** outputSchema for pause_print and resume_print. */
+export const CONTROL_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["status", "message"],
+    properties: {
+        status: { type: "string" },
+        message: { type: "string" },
+        action: { type: "string", enum: ["pause", "resume"] },
+        jobName: { type: "string" },
+    },
+};
+// ---- Value helpers: every optional number is finite or omitted. ----
+export function finiteNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+/** A percentage clamped to 0–100, rounded to 0.1. */
+export function percent(value) {
+    const number = finiteNumber(value);
+    if (number === undefined)
+        return undefined;
+    return Math.round(Math.min(100, Math.max(0, number)) * 10) / 10;
+}
+/** Non-negative whole seconds. */
+export function seconds(value) {
+    const number = finiteNumber(value);
+    if (number === undefined || number < 0)
+        return undefined;
+    return Math.round(number);
+}
+/** A positive integer layer count or index. */
+export function layerNumber(value) {
+    const number = finiteNumber(value);
+    return number !== undefined && number > 0 ? Math.round(number) : undefined;
+}
+export function nonEmptyText(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/** {actual, target} when the actual reading is finite; a missing target means off (0). */
+export function heaterReading(actual, target) {
+    const value = finiteNumber(actual);
+    if (value === undefined)
+        return undefined;
+    return { actual: Math.round(value * 10) / 10, target: Math.round((finiteNumber(target) ?? 0) * 10) / 10 };
+}
+/**
+ * The job name the printer reports, reduced to its file name so it matches the
+ * uploaded `jobName` (Duet reports 0:/gcodes/x.gcode, Klipper gcodes-relative paths).
+ */
+export function remoteJobName(value) {
+    const text = nonEmptyText(value);
+    if (!text)
+        return undefined;
+    const name = path.posix.basename(text.replace(/\\/g, "/").replace(/^\d+:/, ""));
+    return name || undefined;
+}
+/** Remove undefined members recursively so results never carry null/undefined fields. */
+export function compact(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => compact(entry));
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined && entry !== null && !(typeof entry === "number" && !Number.isFinite(entry)))
+            .map(([key, entry]) => [key, compact(entry)]);
+        return Object.fromEntries(entries.filter(([, entry]) => !(entry && typeof entry === "object" && !Array.isArray(entry) && Object.keys(entry).length === 0)));
+    }
+    return value;
+}
+export function progressResult(observedAt, state, parts) {
+    return compact({
+        contract: COUNTERPART_CONTRACT,
+        observedAt,
+        state,
+        job: parts.job,
+        temps: parts.temps,
+        activeFilament: parts.activeFilament,
+        problems: parts.problems ?? [],
+    });
+}

package/dist/counterpart/progress.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-firmware mapping for counterpart_print_progress (PRD §8.4). Each function
+ * is pure: it receives the firmware's own JSON and returns the shared shape.
+ * Sources are cited per mapper; rows marked "simulator" were also checked
+ * against a running instance (see CHANGELOG evidence notes).
+ */
+import { type CounterpartProgress, type ProblemSeverity, type ProgressState } from "./contract.js";
+export interface OctoPrintInputs {
+    job: any;
+    /** GET /api/printer body; undefined when it returned 409 (not operational). */
+    printer?: any;
+    /** prints.last of the selected file, read only when an Operational job has no progress. */
+    lastPrint?: {
+        success?: unknown;
+    };
+}
+export declare function octoPrintState(text: string, completion: number | undefined, hasFile: boolean, lastPrint?: {
+    success?: unknown;
+}): ProgressState;
+export declare function mapOctoPrint(inputs: OctoPrintInputs, observedAt: string): CounterpartProgress;
+export declare function mapMoonraker(status: any, estimatedTime: number | undefined, observedAt: string): CounterpartProgress;
+export declare function mapPrusaLink(status: any, jobDetails: any | undefined, observedAt: string): CounterpartProgress;
+export declare function mapDuet(stateModel: any, jobModel: any, observedAt: string): CounterpartProgress;
+export declare function mapRepetier(printer: any, observedAt: string): CounterpartProgress;
+export declare function mapCrealityDevice(data: any, observedAt: string): CounterpartProgress;
+/** print_error for a user cancel; reported with gcode_state FAILED. */
+export declare const BAMBU_CANCEL_ERROR = 50348044;
+export declare function bambuHmsSeverity(code: number): ProblemSeverity;
+export declare function mapBambu(raw: any, observedAt: string, options: {
+    connected: boolean;
+    model?: string;
+}): CounterpartProgress;