bambu-printer-mcp 1.1.90 → 1.1.91
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.
- package/README.md +43 -0
- package/dist/counterpart/flight-record.d.ts +155 -0
- package/dist/counterpart/flight-record.js +831 -0
- package/dist/counterpart/flight-tools.d.ts +213 -0
- package/dist/counterpart/flight-tools.js +232 -0
- package/dist/counterpart/fresh-frame.d.ts +16 -0
- package/dist/counterpart/fresh-frame.js +26 -0
- package/dist/counterpart/make-3mf.js +1 -4
- package/dist/counterpart/physical-evidence.d.ts +70 -0
- package/dist/counterpart/physical-evidence.js +103 -0
- package/dist/counterpart/print-geometry.d.ts +13 -0
- package/dist/counterpart/print-geometry.js +181 -0
- package/dist/counterpart/remote.js +2 -0
- package/dist/counterpart/schemas.d.ts +32 -0
- package/dist/counterpart/schemas.js +2 -0
- package/dist/counterpart/visual-evidence.d.ts +38 -0
- package/dist/counterpart/visual-evidence.js +155 -0
- package/dist/index.js +24 -1
- package/dist/printers/bambu.d.ts +9 -2
- package/dist/printers/bambu.js +32 -6
- package/dist/safety/print-preview.d.ts +2 -0
- package/dist/safety/print-preview.js +1 -1
- package/dist/slicer/3mf-xml.d.ts +7 -0
- package/dist/slicer/3mf-xml.js +61 -0
- package/dist/stl/stl-manipulator.js +5 -2
- package/dist/tool-annotations.js +2 -0
- package/package.json +2 -1
- package/src/counterpart/flight-record.ts +984 -0
- package/src/counterpart/flight-tools.ts +282 -0
- package/src/counterpart/fresh-frame.ts +45 -0
- package/src/counterpart/make-3mf.ts +1 -5
- package/src/counterpart/physical-evidence.ts +185 -0
- package/src/counterpart/print-geometry.ts +192 -0
- package/src/counterpart/remote.ts +2 -0
- package/src/counterpart/schemas.ts +3 -0
- package/src/counterpart/visual-evidence.ts +212 -0
- package/src/index.ts +25 -2
- package/src/printers/bambu.ts +34 -5
- package/src/safety/print-preview.ts +1 -1
- package/src/slicer/3mf-xml.ts +52 -0
- package/src/stl/stl-manipulator.ts +4 -1
- package/src/tool-annotations.ts +2 -0
package/README.md
CHANGED
|
@@ -643,6 +643,49 @@ Two transports are wired in, picked by `bambu_model`:
|
|
|
643
643
|
|
|
644
644
|
Returns `{ status, format: "image/jpeg", sizeBytes, base64, savedTo?, transport }`. `transport` is `"tcp-6000"` or `"rtsps-322"` so callers can tell which path produced the frame. Pass `save_path` to also write the bytes to disk; otherwise only the base64 payload is returned.
|
|
645
645
|
|
|
646
|
+
#### counterpart_print_record
|
|
647
|
+
|
|
648
|
+
Use `list_jobs: true` to discover the retained job IDs before selecting an older `job_id`. Latest-job reads discover newer dispatches made by another MCP process. The process that authorized dispatch owns report writes while it is alive; after it exits, a restarted observer can take over from the saved record. Concurrent passive MCP sessions read the same disk evidence without overwriting the active recorder. Camera bytes appear once, in `structuredContent`, when `include_frames: true`.
|
|
649
|
+
|
|
650
|
+
Read the flight record of a job this server dispatched, without contacting the printer. Firmware `finished` means the printer finished its commands; it does not verify the physical object.
|
|
651
|
+
|
|
652
|
+
```json
|
|
653
|
+
{"job_id":"optional saved record UUID", "include_frames":false}
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
Omit `job_id` for the latest job on the configured printer; ordinary printer target overrides select another saved printer. The result has `contract: "counterpart/1"`, `status: "recorded" | "unavailable"`, an optional version-1 `record`, and separate `physical` evidence. Bambu records allowlisted native report fields; other adapters retain their existing normalized observations, without inventing fields their firmware/adapter does not expose. A record is established at the existing send-authorization boundary, so a lost transport/helper reply still leaves the exact hash/mapping with `dispatch.outcome: "unconfirmed"`. A successful transport reply marks it `accepted`; a matching active firmware report marks it `observed-active`. These outcomes do not verify physical success or authorize a retry. The record retains the inspected artifact SHA-256, selected plate/hash, filament mapping/materials, timestamped allowlisted state/error/stage/AMS/temperature changes, latest state, truncation count and camera metadata. Printer names, hosts, serials, credentials, arbitrary report text and URLs are excluded; the target and dispatched job identity are hashed. Raw unknown fields remain unknown; AMS `remain: -1` is not empty. After an active report has been seen, firmware terminal reports freeze the job record so later cooling does not evict its failure evidence. Returned task/subtask execution IDs are hashed. A changed execution ID or an observed ended-to-active reprint invalidates current-progress evidence durably (a bounded one-byte marker), including same-filename reprints; explicit archived reads keep the original evidence. History before this feature or outside retained/connected observations is unavailable, not reconstructed by contacting the printer.
|
|
657
|
+
|
|
658
|
+
Storage is private (directory 0700, files 0600), survives MCP restart, and is capped at ten jobs, 1 MiB/2048 report changes per job, a 64 KiB visual-observation sidecar, and 32 JPEGs of at most 512 KiB each. At most four images are returned per request. Older changes/jobs are removed; `droppedReports`, `droppedFrames` and `skippedCheckpoints` disclose gaps. `COUNTERPART_RECORD_DIR` is a trusted server environment override, never a tool-selected filesystem path. Storage failure warns on stderr and marks a record volatile; diagnostics never authorize printing, resume or another mutation.
|
|
659
|
+
|
|
660
|
+
While the client monitors `counterpart_print_progress`, existing reports trigger bounded asynchronous preparation-frame candidates (up to three stage changes), a first-layer frame, a completed-first-layer follow-up when layer 2 is observed, then a snapshot at crossed ten-layer milestones and height fractions (5%, 30%, 60%, 90%). The 32-frame ring preserves baseline/first-layer evidence and the latest recorded empty-footprint anomaly. There is no additional status polling or autonomous watcher. Without a monitoring client, known layer geometry, a matching active job and a usable existing camera source, no physical verdict is inferred. Skipped heights are not backfilled. Each frame binds its ID, actual report layer/time, expected sliced Z, capture receipt/acquisition time and image SHA-256. Image acquisition must be at or after its associated report boundary; an active stream waits for a newer frame when its cached frame predates that boundary. Old cached frames, a layer/state change during acquisition, and bounded camera failures are marked unavailable. A stable reported layer is not a hardware-synchronized shutter. `include_frames:true` reads saved JPEG base64 from disk; it does not open a camera. Expected geometry is the selected 3MF plate's or inspected standalone G-code snapshot's sliced layer Z and extrusion-path XY bounds, including swept extrema for G2/G3 XY arcs, not a calibrated camera silhouette or measured flow. Oversize/unsupported G-code or missing layer reports leave geometry/correspondence unknown.
|
|
661
|
+
|
|
662
|
+
`physical.status` is `unknown`, `consistent`, `suspect_no_growth` or `suspect_no_extrusion`, independently of firmware state. Without a usable client visual observation or calibrated height measurements it remains **unknown**, including after FINISH. When `physical.assessment` is present, the client worker should fetch its `frameId` and any useful `referenceFrameIds` with `counterpart_print_record` using `frame_format:"images"` and optional `frame_ids` (at most four). This returns normal MCP image content exactly once, indexed by `imageContentIndex` in frame metadata. Image format defaults to compact `view:"evidence"`; `omittedReports`/`omittedGeometryLayers` disclose omitted journal detail. `view:"record"` retains the full forensic record. The request includes the selected sliced footprint bounds, layer/height and explicit visibility/deposition criteria.
|
|
663
|
+
|
|
664
|
+
The client vision worker then calls **`counterpart_print_assess`** with:
|
|
665
|
+
|
|
666
|
+
```json
|
|
667
|
+
{"job_id":"saved job UUID","artifact_sha256":"saved dispatch hash","frame_id":"saved frame UUID","image_sha256":"saved JPEG hash","visibility":"clear","footprint_visible":true,"deposition":"absent","attempted":true}
|
|
668
|
+
```
|
|
669
|
+
|
|
670
|
+
The hashes/IDs must match the saved job and image. `visibility` is `clear|dark|occluded|out_of_view|unknown`; `deposition` is `absent|present|unknown`. Set `attempted` only when the frame follows attempted object deposition, and `footprint_visible` only when sufficient expected deposition area can be judged. Optional `reference_frame_id`, `reference_visibility` and `reference_empty` provide empty-bed context. **A clearly visible empty footprint after attempted printing is sufficient for `suspect_no_extrusion`; no reference is required.** A lowered, dark or occluded reference is not proof and does not suppress a clear direct observation. Dark/occluded/unlocatable current evidence stays unknown. Merely visible material does not verify height, coverage or final success.
|
|
671
|
+
|
|
672
|
+
This tool writes only bounded local visual observations (idempotently) and has no printer/camera I/O, model call or control. Observations live separately from the single-writer telemetry journal, so a worker process cannot overwrite live reports. Their result survives MCP restart and firmware FINISH. A `suspect_no_extrusion` warning stays active for the job through later unknown/dark/occluded observations and FINISH; only a later clear `present` observation with a visible footprint at a higher layer may supersede it (without proving final success). It is the first structured progress problem, with the observed layer (`physical.observedLayer`) and separate wording after firmware completion. A first-layer `unknown` observation still permits a new assessment at the crossed ten-layer checkpoint (10, 20, …), subject to fresh reports, available geometry and camera visibility. Image interpretation is the **client worker's** responsibility: the MCP does not contain an image classifier or pretend pixel change proves extrusion. Clients must consume pending assessments and should never announce a first layer is down from a counter alone. Installing these backend tools alone does not add that worker loop to an older client.
|
|
673
|
+
|
|
674
|
+
A worker may also fetch the images/geometry and pass up to four calibrated height measurements to this read tool:
|
|
675
|
+
|
|
676
|
+
```json
|
|
677
|
+
{"measurements":[
|
|
678
|
+
{"frameId":"saved frame UUID", "visible":true, "observedHeightMm":24, "uncertaintyMm":0.5, "method":"calibrated-height"},
|
|
679
|
+
{"frameId":"another saved frame UUID", "visible":true, "observedHeightMm":24, "uncertaintyMm":0.5, "method":"calibrated-height"}
|
|
680
|
+
]}
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
The MCP validates the saved frame identities/times and evaluates these **client-supplied** measurements; it runs no vision model. Two visible, sufficiently separated expected heights can support consistency, or an unchanged short observed height can support `suspect_no_growth`. Occluded, out-of-view, uncalibrated, uncertain, stale or contradictory evidence stays unknown. `consistent` concerns height in those frames only; it does not verify final shape, strength or print success. The assessment returns frame IDs and explicit limitations and is computed without altering the record. There is no automatic stop, pause, resume, model call or printer-setting change.
|
|
684
|
+
|
|
685
|
+
Sensor limits: Bambu Studio v02.08.02.61 declares [P1S lidar calibration unavailable](https://github.com/bambulab/BambuStudio/blob/v02.08.02.61/resources/printers/C12.json#L37), [X1 Carbon lidar calibration available](https://github.com/bambulab/BambuStudio/blob/v02.08.02.61/resources/printers/BL-P001.json#L42), and [H2D calibration/wrapping capabilities](https://github.com/bambulab/BambuStudio/blob/v02.08.02.61/resources/printers/O1D.json#L51). These are capability/configuration facts, not deposited-height measurements. Studio parses [xcam detection options and live support bits](https://github.com/bambulab/BambuStudio/blob/v02.08.02.61/src/slic3r/GUI/DeviceCore/DevPrintOptions.cpp#L37) and [AMS air-print capability with firmware exceptions](https://github.com/bambulab/BambuStudio/blob/v02.08.02.61/src/slic3r/GUI/DeviceManager.cpp#L1112). This feature records reported evidence; it never enables a detector or assumes a capability from a model name.
|
|
686
|
+
|
|
687
|
+
Validation is offline replay and mocked transports only. No real-printer physical-success claim is made.
|
|
688
|
+
|
|
646
689
|
#### camera_stream_start, camera_frame, camera_stream_stop
|
|
647
690
|
|
|
648
691
|
Development capability; discover these tools before using them with an installed server. Start one shared camera connection while a viewer is open, then request changed frames. The connection closes after 30 seconds without a viewer request. Snapshots reuse its latest frame. A1/P1 use the existing TLS protocol; X1/H2/P2S use one ffmpeg process for the stream lifetime.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
import { type VisualSubmission, type VisualObservation } from "./visual-evidence.js";
|
|
2
|
+
import type { PrintGeometry } from "./print-geometry.js";
|
|
3
|
+
import { type EvidenceFrame, type HeightMeasurement } from "./physical-evidence.js";
|
|
4
|
+
export type { PrintGeometry, HeightMeasurement };
|
|
5
|
+
export declare const flightKey: (host: string, serial: string) => string;
|
|
6
|
+
/** An allowlist, not a recursive dump/redactor. Unknown fields and arbitrary strings never reach disk. */
|
|
7
|
+
export declare function flightSnapshot(raw: Record<string, any>): Record<string, unknown>;
|
|
8
|
+
export interface FlightDispatch {
|
|
9
|
+
sha256: string;
|
|
10
|
+
jobName: string;
|
|
11
|
+
mapping?: number[];
|
|
12
|
+
materials?: string[];
|
|
13
|
+
plate?: {
|
|
14
|
+
index: number;
|
|
15
|
+
sha256: string;
|
|
16
|
+
};
|
|
17
|
+
expected?: PrintGeometry;
|
|
18
|
+
}
|
|
19
|
+
interface StoredDispatch extends Omit<FlightDispatch, "jobName" | "expected"> {
|
|
20
|
+
jobHash: string;
|
|
21
|
+
outcome: "unconfirmed" | "accepted" | "observed-active";
|
|
22
|
+
acceptedAt?: string;
|
|
23
|
+
}
|
|
24
|
+
export interface FlightRecord {
|
|
25
|
+
version: 1;
|
|
26
|
+
seenActive: boolean;
|
|
27
|
+
owner?: {
|
|
28
|
+
pid: number;
|
|
29
|
+
token: string;
|
|
30
|
+
};
|
|
31
|
+
endedAt?: string;
|
|
32
|
+
execution?: Record<string, string>;
|
|
33
|
+
executionSuperseded?: boolean;
|
|
34
|
+
id: string;
|
|
35
|
+
printerKey: string;
|
|
36
|
+
dispatchedAt: string;
|
|
37
|
+
dispatch: StoredDispatch;
|
|
38
|
+
expected?: PrintGeometry;
|
|
39
|
+
reports: Array<{
|
|
40
|
+
seq: number;
|
|
41
|
+
at: string;
|
|
42
|
+
changes: Record<string, unknown>;
|
|
43
|
+
}>;
|
|
44
|
+
latest: Record<string, unknown>;
|
|
45
|
+
droppedReports: number;
|
|
46
|
+
nextSeq: number;
|
|
47
|
+
frames: EvidenceFrame[];
|
|
48
|
+
skippedCheckpoints: number[];
|
|
49
|
+
droppedFrames: number;
|
|
50
|
+
sampledCheckpoints?: number[];
|
|
51
|
+
visualObservations?: VisualObservation[];
|
|
52
|
+
omittedReports?: number;
|
|
53
|
+
omittedGeometryLayers?: number;
|
|
54
|
+
storage: "durable" | "volatile";
|
|
55
|
+
}
|
|
56
|
+
export interface ReadRecordOptions {
|
|
57
|
+
evidenceOnly?: boolean;
|
|
58
|
+
frameIds?: string[];
|
|
59
|
+
listJobs?: boolean;
|
|
60
|
+
jobId?: string;
|
|
61
|
+
includeFrames?: boolean;
|
|
62
|
+
measurements?: HeightMeasurement[];
|
|
63
|
+
}
|
|
64
|
+
export declare class FlightRecords {
|
|
65
|
+
private readonly dir;
|
|
66
|
+
private readonly now;
|
|
67
|
+
private readonly maxEvents;
|
|
68
|
+
private readonly maxJobs;
|
|
69
|
+
private readonly maxBytes;
|
|
70
|
+
private readonly maxCaptureMs;
|
|
71
|
+
private readonly cache;
|
|
72
|
+
private readonly pending;
|
|
73
|
+
private readonly recentReports;
|
|
74
|
+
private readonly superseded;
|
|
75
|
+
private warned;
|
|
76
|
+
private readonly ownerToken;
|
|
77
|
+
constructor(options?: {
|
|
78
|
+
dir?: string;
|
|
79
|
+
now?: () => number;
|
|
80
|
+
maxEvents?: number;
|
|
81
|
+
maxJobs?: number;
|
|
82
|
+
maxBytes?: number;
|
|
83
|
+
maxCaptureMs?: number;
|
|
84
|
+
});
|
|
85
|
+
begin(key: string, input: FlightDispatch): string;
|
|
86
|
+
accept(key: string, jobName: string): boolean;
|
|
87
|
+
observe(key: string, raw: Record<string, any>, at?: number): void;
|
|
88
|
+
/** Progress may expose saved evidence only for the job in this returned report. */
|
|
89
|
+
physicalForReport(key: string, raw: Record<string, any> | null | undefined): import("./physical-evidence.js").PhysicalEvidence;
|
|
90
|
+
read(key: string, options?: ReadRecordOptions): {
|
|
91
|
+
physical: import("./physical-evidence.js").PhysicalEvidence;
|
|
92
|
+
jobs?: {
|
|
93
|
+
id: string;
|
|
94
|
+
dispatchedAt: string;
|
|
95
|
+
sha256: string;
|
|
96
|
+
outcome: "accepted" | "unconfirmed" | "observed-active";
|
|
97
|
+
}[] | undefined;
|
|
98
|
+
contract: "counterpart/1";
|
|
99
|
+
status: "unavailable";
|
|
100
|
+
} | {
|
|
101
|
+
record: FlightRecord;
|
|
102
|
+
physical: import("./physical-evidence.js").PhysicalEvidence;
|
|
103
|
+
jobs?: {
|
|
104
|
+
id: string;
|
|
105
|
+
dispatchedAt: string;
|
|
106
|
+
sha256: string;
|
|
107
|
+
outcome: "accepted" | "unconfirmed" | "observed-active";
|
|
108
|
+
}[] | undefined;
|
|
109
|
+
contract: "counterpart/1";
|
|
110
|
+
status: "recorded";
|
|
111
|
+
};
|
|
112
|
+
/** Persist only the client's frame-bound visual observation, without printer I/O or journal ownership changes. */
|
|
113
|
+
submitVisual(key: string, input: VisualSubmission): {
|
|
114
|
+
physical: import("./physical-evidence.js").PhysicalEvidence;
|
|
115
|
+
jobs?: {
|
|
116
|
+
id: string;
|
|
117
|
+
dispatchedAt: string;
|
|
118
|
+
sha256: string;
|
|
119
|
+
outcome: "accepted" | "unconfirmed" | "observed-active";
|
|
120
|
+
}[] | undefined;
|
|
121
|
+
contract: "counterpart/1";
|
|
122
|
+
status: "unavailable";
|
|
123
|
+
} | {
|
|
124
|
+
record: FlightRecord;
|
|
125
|
+
physical: import("./physical-evidence.js").PhysicalEvidence;
|
|
126
|
+
jobs?: {
|
|
127
|
+
id: string;
|
|
128
|
+
dispatchedAt: string;
|
|
129
|
+
sha256: string;
|
|
130
|
+
outcome: "accepted" | "unconfirmed" | "observed-active";
|
|
131
|
+
}[] | undefined;
|
|
132
|
+
contract: "counterpart/1";
|
|
133
|
+
status: "recorded";
|
|
134
|
+
};
|
|
135
|
+
private visualFile;
|
|
136
|
+
private visuals;
|
|
137
|
+
private trimFrames;
|
|
138
|
+
/** Called only after existing reports/reads, never on a timer; a sample cannot block the print. */
|
|
139
|
+
sample(key: string, capture: (capturedAfter: string) => Promise<{
|
|
140
|
+
base64?: string;
|
|
141
|
+
capturedAt?: string;
|
|
142
|
+
}>): Promise<void>;
|
|
143
|
+
/** One process writes a dispatched job; fresh observations can take over after its process exits. */
|
|
144
|
+
private canWrite;
|
|
145
|
+
private jobSummaries;
|
|
146
|
+
private isSuperseded;
|
|
147
|
+
/** Monotonic one-byte sidecar: another observer cannot overwrite the live owner's journal. */
|
|
148
|
+
private invalidateExecution;
|
|
149
|
+
private file;
|
|
150
|
+
private frameFile;
|
|
151
|
+
private files;
|
|
152
|
+
private get;
|
|
153
|
+
private save;
|
|
154
|
+
private prune;
|
|
155
|
+
}
|