mcp-3d-printer-server 1.2.20 → 1.2.21

package/src/counterpart/contract.ts

@@ -0,0 +1,326 @@
+/**
+ * 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"] as const;
+export type PrinterKind = (typeof PRINTER_KINDS)[number];
+
+export const PROGRESS_STATES = ["idle", "preparing", "printing", "paused", "finished", "failed", "cancelled", "offline", "busy"] as const;
+export type ProgressState = (typeof PROGRESS_STATES)[number];
+
+export const PROBLEM_SEVERITIES = ["fatal", "error", "warning", "info"] as const;
+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;
+}
+
+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" },
+      },
+    },
+  },
+} as const;
+
+/** 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 },
+  },
+} as const;
+
+/** 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" },
+  },
+} as const;
+
+/** 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.",
+          },
+        },
+      },
+    },
+  },
+} as const;
+
+/** 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" },
+  },
+} as const;
+
+// ---- Value helpers: every optional number is finite or omitted. ----
+
+export function finiteNumber(value: unknown): number | undefined {
+  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: unknown): number | undefined {
+  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: unknown): number | undefined {
+  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: unknown): number | undefined {
+  const number = finiteNumber(value);
+  return number !== undefined && number > 0 ? Math.round(number) : undefined;
+}
+
+export function nonEmptyText(value: unknown): string | undefined {
+  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: unknown, target: unknown): HeaterReading | undefined {
+  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: unknown): string | undefined {
+  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<T>(value: T): T {
+  if (Array.isArray(value)) return value.map((entry) => compact(entry)) as unknown as T;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .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 as object).length === 0)
+    )) as T;
+  }
+  return value;
+}
+
+export function progressResult(
+  observedAt: string,
+  state: ProgressState,
+  parts: Omit<Partial<CounterpartProgress>, "contract" | "observedAt" | "state">
+): CounterpartProgress {
+  return compact({
+    contract: COUNTERPART_CONTRACT,
+    observedAt,
+    state,
+    job: parts.job,
+    temps: parts.temps,
+    activeFilament: parts.activeFilament,
+    problems: parts.problems ?? [],
+  }) as CounterpartProgress;
+}