bambu-printer-mcp 1.1.52 → 1.1.54

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 CHANGED
@@ -1200,8 +1200,11 @@ When `slicer_type` is `bambustudio` (the default), these additional parameters a
1200
1200
  | `layer_height` | number | Layer height in mm, such as 0.28, 0.2 or 0.12; at most the nozzle diameter |
1201
1201
  | `wall_loops` | integer | Number of walls, 0 to 1000 |
1202
1202
  | `sparse_infill_density` | string | Sparse infill density, such as `"15%"` |
1203
+ | `enable_support` | boolean | Turn support generation on or off |
1204
+ | `support_type` | string | `normal(auto)`, `tree(auto)`, `normal(manual)` or `tree(manual)` |
1205
+ | `support_threshold_angle` | integer | Overhang threshold for automatic supports, 0 to 90 degrees (0 lets the slicer decide) |
1203
1206
 
1204
- `layer_height`, `wall_loops` and `sparse_infill_density` are written as a process override on top of the machine and process preset the tool resolves, using Bambu Studio's keys and string forms (`"0.2"`, `"2"`, `"15%"`). Every other preset value, and the machine preset, stay as resolved, and your own profile files are not changed. They work with every Bambu-compatible slicer, including remote `orca-slicer-api` slicing, and are refused for PrusaSlicer, Slic3r and Cura.
1207
+ `layer_height`, `wall_loops`, `sparse_infill_density` and the three support arguments are written as a process override on top of the machine and process preset the tool resolves, using Bambu Studio's keys and string forms (`"0.2"`, `"2"`, `"15%"`). Every other preset value, and the machine preset, stay as resolved, and your own profile files are not changed. They work with every Bambu-compatible slicer, including remote `orca-slicer-api` slicing, and are refused for PrusaSlicer, Slic3r and Cura.
1205
1208
 
1206
1209
  **Example: Slice with auto-orient and 3 copies**
1207
1210
  ```json
package/dist/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import { CAMERA_STREAM_TOOLS } from "./printers/camera-tools.js";
3
+ import { withAnnotations } from "./tool-annotations.js";
3
4
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
4
5
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
5
6
  import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -2120,7 +2121,10 @@ class BambuPrinterMCPServer {
2120
2121
  slice_plate: { type: "number", description: "Which plate index to slice. 0 = all plates for local slicers; remote slicing defaults to plate 1 and rejects 0. Use 1, 2, etc. to slice only a specific plate in multi-plate 3MF projects." },
2121
2122
  layer_height: { type: "number", exclusiveMinimum: 0, description: "Layer height in mm, such as 0.28 (draft), 0.2 (standard) or 0.12 (fine). Written as the process preset's layer_height over the machine and process preset this tool resolves; at most the nozzle diameter. Bambu-compatible slicers only." },
2122
2123
  wall_loops: { type: "integer", minimum: 0, maximum: 1000, description: "Number of walls (perimeters), written as the process preset's wall_loops. Bambu-compatible slicers only." },
2123
- sparse_infill_density: { type: "string", pattern: "^\\s*\\d+(\\.\\d+)?\\s*%\\s*$", description: "Sparse infill density as a percentage, such as \"15%\", written as the process preset's sparse_infill_density. Bambu-compatible slicers only." }
2124
+ sparse_infill_density: { type: "string", pattern: "^\\s*\\d+(\\.\\d+)?\\s*%\\s*$", description: "Sparse infill density as a percentage, such as \"15%\", written as the process preset's sparse_infill_density. Bambu-compatible slicers only." },
2125
+ enable_support: { type: "boolean", description: "Turn support generation on or off, written as the process preset's enable_support. Bambu-compatible slicers only." },
2126
+ support_type: { type: "string", enum: ["normal(auto)", "tree(auto)", "normal(manual)", "tree(manual)"], description: "Support style, written as the process preset's support_type. Bambu-compatible slicers only." },
2127
+ support_threshold_angle: { type: "integer", minimum: 0, maximum: 90, description: "Overhang threshold in degrees for automatic supports, written as the process preset's support_threshold_angle (0 lets the slicer decide). Bambu-compatible slicers only." }
2124
2128
  },
2125
2129
  required: ["stl_path", "bambu_model"]
2126
2130
  }
@@ -2592,7 +2596,6 @@ class BambuPrinterMCPServer {
2592
2596
  {
2593
2597
  name: "inspect_print_file",
2594
2598
  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.",
2595
- annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
2596
2599
  inputSchema: {
2597
2600
  type: "object",
2598
2601
  additionalProperties: false,
@@ -2817,8 +2820,7 @@ class BambuPrinterMCPServer {
2817
2820
  bambu_token: { type: "string", description: "Access token (default: value from env); never returned." }
2818
2821
  }
2819
2822
  },
2820
- outputSchema: PRINTER_INFO_OUTPUT_SCHEMA,
2821
- annotations: { readOnlyHint: true }
2823
+ outputSchema: PRINTER_INFO_OUTPUT_SCHEMA
2822
2824
  },
2823
2825
  {
2824
2826
  name: "counterpart_print_route",
@@ -2843,8 +2845,7 @@ class BambuPrinterMCPServer {
2843
2845
  bambu_token: { type: "string", description: "Access token (default: value from env)" }
2844
2846
  }
2845
2847
  },
2846
- outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA,
2847
- annotations: { readOnlyHint: true }
2848
+ outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA
2848
2849
  },
2849
2850
  {
2850
2851
  name: "counterpart_make_3mf",
@@ -2934,7 +2935,7 @@ class BambuPrinterMCPServer {
2934
2935
  },
2935
2936
  outputSchema: FUSION_EXPORT_OUTPUT_SCHEMA
2936
2937
  }
2937
- ]
2938
+ ].map(withAnnotations)
2938
2939
  };
2939
2940
  });
2940
2941
  this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
@@ -1,11 +1,13 @@
1
1
  /**
2
- * slice_stl's layer_height, wall_loops and sparse_infill_density arguments
2
+ * slice_stl's layer_height, wall_loops, sparse_infill_density and support arguments
3
3
  * (PRD §8.4). They are written over the process preset the slicer already
4
4
  * resolved, using Bambu Studio/Orca keys and their string forms ("0.2", "2",
5
5
  * "15%"), so the machine preset and every other process value stay as resolved.
6
6
  */
7
- export type ProcessOverrides = Partial<Record<"layer_height" | "wall_loops" | "sparse_infill_density", string>>;
8
- export declare const PROCESS_OVERRIDE_KEYS: readonly ["layer_height", "wall_loops", "sparse_infill_density"];
7
+ export declare const PROCESS_OVERRIDE_KEYS: readonly ["layer_height", "wall_loops", "sparse_infill_density", "enable_support", "support_type", "support_threshold_angle"];
8
+ export type ProcessOverrides = Partial<Record<(typeof PROCESS_OVERRIDE_KEYS)[number], string>>;
9
+ /** Bambu Studio's and OrcaSlicer's support_type values. */
10
+ export declare const SUPPORT_TYPES: readonly ["normal(auto)", "tree(auto)", "normal(manual)", "tree(manual)"];
9
11
  /** Validate the tool arguments; undefined when none are given. */
10
12
  export declare function parseProcessOverrides(args: Record<string, unknown> | undefined, nozzleDiameter: number): ProcessOverrides | undefined;
11
13
  /** The process profile with the overrides written over its values. */
@@ -1,4 +1,12 @@
1
- export const PROCESS_OVERRIDE_KEYS = ["layer_height", "wall_loops", "sparse_infill_density"];
1
+ /**
2
+ * slice_stl's layer_height, wall_loops, sparse_infill_density and support arguments
3
+ * (PRD §8.4). They are written over the process preset the slicer already
4
+ * resolved, using Bambu Studio/Orca keys and their string forms ("0.2", "2",
5
+ * "15%"), so the machine preset and every other process value stay as resolved.
6
+ */
7
+ export const PROCESS_OVERRIDE_KEYS = ["layer_height", "wall_loops", "sparse_infill_density", "enable_support", "support_type", "support_threshold_angle"];
8
+ /** Bambu Studio's and OrcaSlicer's support_type values. */
9
+ export const SUPPORT_TYPES = ["normal(auto)", "tree(auto)", "normal(manual)", "tree(manual)"];
2
10
  /** Validate the tool arguments; undefined when none are given. */
3
11
  export function parseProcessOverrides(args, nozzleDiameter) {
4
12
  const overrides = {};
@@ -25,6 +33,27 @@ export function parseProcessOverrides(args, nozzleDiameter) {
25
33
  throw new Error('sparse_infill_density must be a percentage from 0% to 100%, such as "15%".');
26
34
  overrides.sparse_infill_density = `${Number(match[1])}%`;
27
35
  }
36
+ const enableSupport = args?.enable_support;
37
+ if (enableSupport !== undefined) {
38
+ if (typeof enableSupport !== "boolean")
39
+ throw new Error("enable_support must be true or false.");
40
+ overrides.enable_support = enableSupport ? "1" : "0";
41
+ }
42
+ const supportType = args?.support_type;
43
+ if (supportType !== undefined) {
44
+ if (typeof supportType !== "string" || !SUPPORT_TYPES.includes(supportType)) {
45
+ throw new Error(`support_type must be one of ${SUPPORT_TYPES.join(", ")}.`);
46
+ }
47
+ overrides.support_type = supportType;
48
+ }
49
+ const threshold = args?.support_threshold_angle;
50
+ if (threshold !== undefined) {
51
+ // Studio's threshold angle runs 0-90 degrees; 0 lets the slicer pick by its own rule.
52
+ if (typeof threshold !== "number" || !Number.isInteger(threshold) || threshold < 0 || threshold > 90) {
53
+ throw new Error("support_threshold_angle must be an integer number of degrees from 0 to 90.");
54
+ }
55
+ overrides.support_threshold_angle = String(threshold);
56
+ }
28
57
  return Object.keys(overrides).length ? overrides : undefined;
29
58
  }
30
59
  /** The process profile with the overrides written over its values. */
@@ -0,0 +1,25 @@
1
+ /**
2
+ * MCP tool annotations (spec 2025-03-26 and later), one entry per tool, chosen from
3
+ * what the tool's handler actually does. Clients and Counterpart's remote endpoint
4
+ * read them to decide which tools a device may call, so every listed tool must have
5
+ * one (tests/tool-annotations.test.mjs).
6
+ *
7
+ * readOnlyHint: changes nothing outside this server (printer, files, other apps).
8
+ * destructiveHint: may delete, overwrite, end or irreversibly change something.
9
+ * idempotentHint: repeating the call with the same arguments has no further effect.
10
+ * openWorldHint: reaches something outside this server and its files: the printer,
11
+ * Bambu Cloud, a remote slicer, or another application (Blender, Fusion, Bambu Connect).
12
+ */
13
+ export interface ToolAnnotations {
14
+ readOnlyHint: boolean;
15
+ destructiveHint: boolean;
16
+ idempotentHint: boolean;
17
+ openWorldHint: boolean;
18
+ }
19
+ export declare const TOOL_ANNOTATIONS: Record<string, ToolAnnotations>;
20
+ /** The tool with its annotations. */
21
+ export declare function withAnnotations<T extends {
22
+ name: string;
23
+ }>(tool: T): T & {
24
+ annotations: ToolAnnotations;
25
+ };
@@ -0,0 +1,96 @@
1
+ const hints = (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) => ({ readOnlyHint, destructiveHint, idempotentHint, openWorldHint });
2
+ /** Reads the printer or another outside system; changes nothing. */
3
+ const READ_OUTSIDE = hints(true, false, true, true);
4
+ /** Reads local files or this server's configuration only. */
5
+ const READ_LOCAL = hints(true, false, true, false);
6
+ /** Writes a fixed-name output into this server's temporary directory, replacing an earlier output of that name; inputs untouched. */
7
+ const LOCAL_OUTPUT = hints(false, true, true, false);
8
+ /** Sets a printer setting to a given value; setting it again changes nothing. */
9
+ const SET_PRINTER = hints(false, false, true, true);
10
+ /** Starts a print job: adds a job, removes nothing, but a repeat would start another. */
11
+ const START_PRINT = hints(false, false, false, true);
12
+ /** Starts a print, auto-slicing an unsliced project first, which replaces an earlier slice output of that name. */
13
+ const SLICE_AND_PRINT = hints(false, true, false, true);
14
+ export const TOOL_ANNOTATIONS = {
15
+ // Printer and cloud reads
16
+ get_printer_status: READ_OUTSIDE,
17
+ get_printer_filaments: READ_OUTSIDE,
18
+ resolve_3mf_ams_slots: READ_OUTSIDE, // reads the live AMS inventory
19
+ list_printer_files: READ_OUTSIDE,
20
+ counterpart_print_progress: READ_OUTSIDE,
21
+ // connect: true starts the bridge agent, which writes its configuration and device identity and can replace certificates.
22
+ bambu_network_bridge_status: hints(false, true, true, true),
23
+ camera_frame: READ_OUTSIDE,
24
+ // Open (or renew) and close the one camera connection all viewers of this printer share; no printer motion or commands.
25
+ camera_stream_start: hints(false, false, true, true),
26
+ camera_stream_stop: hints(false, false, true, true),
27
+ // Writes save_path, overwriting an existing file there; every call takes a new frame.
28
+ camera_snapshot: hints(false, true, false, true),
29
+ // Local reads
30
+ inspect_print_file: READ_LOCAL,
31
+ list_3mf_plate_objects: READ_LOCAL,
32
+ get_stl_info: READ_LOCAL,
33
+ list_templates: READ_LOCAL,
34
+ get_slice_settings: LOCAL_OUTPUT, // a 3MF's settings are extracted to a fixed file in the temporary directory
35
+ counterpart_printer_info: READ_LOCAL, // configuration and capabilities; sends nothing to the printer
36
+ // Local outputs in the server's temporary directory
37
+ extend_stl_base: LOCAL_OUTPUT,
38
+ scale_stl: LOCAL_OUTPUT,
39
+ rotate_stl: LOCAL_OUTPUT,
40
+ merge_vertices: LOCAL_OUTPUT,
41
+ center_model: LOCAL_OUTPUT,
42
+ lay_flat: LOCAL_OUTPUT,
43
+ // Same, but a configured orca-slicer-api slices on a remote service, a new job and output each call.
44
+ slice_stl: hints(false, true, false, true),
45
+ slice_with_template: hints(false, true, false, true),
46
+ // New 3MF at a caller-chosen path; never overwrites, so a repeat fails and changes nothing.
47
+ counterpart_make_3mf: hints(false, false, true, false),
48
+ // Copies into the template registry, replacing a template of the same name.
49
+ save_template: hints(false, true, true, false),
50
+ // Replaces BAMBU_DEFAULT_CONNECTION_MODE/TYPE in .env and in this process.
51
+ counterpart_print_route: hints(false, true, true, false),
52
+ // Print starts
53
+ start_print: START_PRINT,
54
+ start_print_job: START_PRINT,
55
+ print_3mf: SLICE_AND_PRINT,
56
+ print_3mf_bambu_network: SLICE_AND_PRINT,
57
+ print_collar_charm: SLICE_AND_PRINT,
58
+ upload_file: START_PRINT, // print: true starts the uploaded G-code; uploads never overwrite (unique names)
59
+ upload_gcode: hints(false, false, false, true), // a uniquely named new copy per call
60
+ // Print controls
61
+ pause_print: SET_PRINTER,
62
+ resume_print: SET_PRINTER,
63
+ cancel_print: hints(false, true, true, true), // ends the job; it cannot be resumed
64
+ skip_objects: hints(false, true, true, true), // skipped objects are not printed and cannot be restored
65
+ // Printer settings
66
+ set_print_speed: SET_PRINTER,
67
+ set_airduct_mode: SET_PRINTER,
68
+ set_temperature: SET_PRINTER,
69
+ set_fan_speed: SET_PRINTER,
70
+ set_light: SET_PRINTER,
71
+ set_ams_drying: SET_PRINTER,
72
+ reread_ams_rfid: hints(false, false, false, true), // moves AMS filament on every call
73
+ // Replaces stored AMS metadata or the calibration selection on an X2D.
74
+ x2d_native_control: hints(false, true, true, true),
75
+ clear_hms_errors: hints(false, true, true, true), // clears the printer's error record
76
+ delete_printer_file: hints(false, true, true, true),
77
+ // Only handshake and sign-in reads are allowed, but with_agent (the default) starts the bridge agent like the status probe.
78
+ bambu_network_call: hints(false, true, true, true),
79
+ // Opens the file in the Bambu Connect app; does not print.
80
+ bambu_connect_import_file: hints(false, false, false, true),
81
+ // Blender and Fusion
82
+ blender_mcp_status: READ_OUTSIDE, // connects and lists tools; edits nothing
83
+ blender_mcp_call: hints(false, true, false, true), // any Blender tool, including execute_blender_code
84
+ // The standard route preserves scene objects and needs a new output path; a configured legacy bridge promises neither.
85
+ blender_mcp_edit_model: hints(false, true, false, true),
86
+ fusion_mcp_status: hints(false, false, true, true), // launch: true starts Fusion on this computer
87
+ fusion_mcp_call: hints(false, true, false, true), // any Fusion tool, including execute_code
88
+ fusion_mcp_new_design: hints(false, false, false, true), // opens another new document
89
+ fusion_mcp_export: hints(false, false, true, true), // never overwrites; a repeat fails and changes nothing
90
+ };
91
+ /** Assumed for a tool missing from the table (a bug the tests catch): the least a client should trust it. */
92
+ const UNKNOWN = hints(false, true, false, true);
93
+ /** The tool with its annotations. */
94
+ export function withAnnotations(tool) {
95
+ return { ...tool, annotations: TOOL_ANNOTATIONS[tool.name] ?? UNKNOWN };
96
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bambu-printer-mcp",
3
- "version": "1.1.52",
3
+ "version": "1.1.54",
4
4
  "description": "MCP server for Bambu Lab 3D printers with STL manipulation, slicing, and print management",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
package/src/index.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import {CAMERA_STREAM_TOOLS} from "./printers/camera-tools.js";
3
+ import { withAnnotations } from "./tool-annotations.js";
3
4
 
4
5
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
5
6
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -2653,7 +2654,10 @@ class BambuPrinterMCPServer {
2653
2654
  slice_plate: { type: "number", description: "Which plate index to slice. 0 = all plates for local slicers; remote slicing defaults to plate 1 and rejects 0. Use 1, 2, etc. to slice only a specific plate in multi-plate 3MF projects." },
2654
2655
  layer_height: { type: "number", exclusiveMinimum: 0, description: "Layer height in mm, such as 0.28 (draft), 0.2 (standard) or 0.12 (fine). Written as the process preset's layer_height over the machine and process preset this tool resolves; at most the nozzle diameter. Bambu-compatible slicers only." },
2655
2656
  wall_loops: { type: "integer", minimum: 0, maximum: 1000, description: "Number of walls (perimeters), written as the process preset's wall_loops. Bambu-compatible slicers only." },
2656
- sparse_infill_density: { type: "string", pattern: "^\\s*\\d+(\\.\\d+)?\\s*%\\s*$", description: "Sparse infill density as a percentage, such as \"15%\", written as the process preset's sparse_infill_density. Bambu-compatible slicers only." }
2657
+ sparse_infill_density: { type: "string", pattern: "^\\s*\\d+(\\.\\d+)?\\s*%\\s*$", description: "Sparse infill density as a percentage, such as \"15%\", written as the process preset's sparse_infill_density. Bambu-compatible slicers only." },
2658
+ enable_support: { type: "boolean", description: "Turn support generation on or off, written as the process preset's enable_support. Bambu-compatible slicers only." },
2659
+ support_type: { type: "string", enum: ["normal(auto)", "tree(auto)", "normal(manual)", "tree(manual)"], description: "Support style, written as the process preset's support_type. Bambu-compatible slicers only." },
2660
+ support_threshold_angle: { type: "integer", minimum: 0, maximum: 90, description: "Overhang threshold in degrees for automatic supports, written as the process preset's support_threshold_angle (0 lets the slicer decide). Bambu-compatible slicers only." }
2657
2661
  },
2658
2662
  required: ["stl_path", "bambu_model"]
2659
2663
  }
@@ -3125,7 +3129,6 @@ class BambuPrinterMCPServer {
3125
3129
  {
3126
3130
  name: "inspect_print_file",
3127
3131
  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.",
3128
- annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
3129
3132
  inputSchema: {
3130
3133
  type: "object",
3131
3134
  additionalProperties: false,
@@ -3350,8 +3353,7 @@ class BambuPrinterMCPServer {
3350
3353
  bambu_token: { type: "string", description: "Access token (default: value from env); never returned." }
3351
3354
  }
3352
3355
  },
3353
- outputSchema: PRINTER_INFO_OUTPUT_SCHEMA,
3354
- annotations: { readOnlyHint: true }
3356
+ outputSchema: PRINTER_INFO_OUTPUT_SCHEMA
3355
3357
  },
3356
3358
  {
3357
3359
  name: "counterpart_print_route",
@@ -3376,8 +3378,7 @@ class BambuPrinterMCPServer {
3376
3378
  bambu_token: { type: "string", description: "Access token (default: value from env)" }
3377
3379
  }
3378
3380
  },
3379
- outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA,
3380
- annotations: { readOnlyHint: true }
3381
+ outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA
3381
3382
  },
3382
3383
  {
3383
3384
  name: "counterpart_make_3mf",
@@ -3467,7 +3468,7 @@ class BambuPrinterMCPServer {
3467
3468
  },
3468
3469
  outputSchema: FUSION_EXPORT_OUTPUT_SCHEMA
3469
3470
  }
3470
- ]
3471
+ ].map(withAnnotations)
3471
3472
  };
3472
3473
  });
3473
3474
 
@@ -1,12 +1,15 @@
1
1
  /**
2
- * slice_stl's layer_height, wall_loops and sparse_infill_density arguments
2
+ * slice_stl's layer_height, wall_loops, sparse_infill_density and support arguments
3
3
  * (PRD §8.4). They are written over the process preset the slicer already
4
4
  * resolved, using Bambu Studio/Orca keys and their string forms ("0.2", "2",
5
5
  * "15%"), so the machine preset and every other process value stay as resolved.
6
6
  */
7
- export type ProcessOverrides = Partial<Record<"layer_height" | "wall_loops" | "sparse_infill_density", string>>;
7
+ export const PROCESS_OVERRIDE_KEYS = ["layer_height", "wall_loops", "sparse_infill_density", "enable_support", "support_type", "support_threshold_angle"] as const;
8
8
 
9
- export const PROCESS_OVERRIDE_KEYS = ["layer_height", "wall_loops", "sparse_infill_density"] as const;
9
+ export type ProcessOverrides = Partial<Record<(typeof PROCESS_OVERRIDE_KEYS)[number], string>>;
10
+
11
+ /** Bambu Studio's and OrcaSlicer's support_type values. */
12
+ export const SUPPORT_TYPES = ["normal(auto)", "tree(auto)", "normal(manual)", "tree(manual)"] as const;
10
13
 
11
14
  /** Validate the tool arguments; undefined when none are given. */
12
15
  export function parseProcessOverrides(args: Record<string, unknown> | undefined, nozzleDiameter: number): ProcessOverrides | undefined {
@@ -33,6 +36,26 @@ export function parseProcessOverrides(args: Record<string, unknown> | undefined,
33
36
  if (!match || Number(match[1]) > 100) throw new Error('sparse_infill_density must be a percentage from 0% to 100%, such as "15%".');
34
37
  overrides.sparse_infill_density = `${Number(match[1])}%`;
35
38
  }
39
+ const enableSupport = args?.enable_support;
40
+ if (enableSupport !== undefined) {
41
+ if (typeof enableSupport !== "boolean") throw new Error("enable_support must be true or false.");
42
+ overrides.enable_support = enableSupport ? "1" : "0";
43
+ }
44
+ const supportType = args?.support_type;
45
+ if (supportType !== undefined) {
46
+ if (typeof supportType !== "string" || !(SUPPORT_TYPES as readonly string[]).includes(supportType)) {
47
+ throw new Error(`support_type must be one of ${SUPPORT_TYPES.join(", ")}.`);
48
+ }
49
+ overrides.support_type = supportType;
50
+ }
51
+ const threshold = args?.support_threshold_angle;
52
+ if (threshold !== undefined) {
53
+ // Studio's threshold angle runs 0-90 degrees; 0 lets the slicer pick by its own rule.
54
+ if (typeof threshold !== "number" || !Number.isInteger(threshold) || threshold < 0 || threshold > 90) {
55
+ throw new Error("support_threshold_angle must be an integer number of degrees from 0 to 90.");
56
+ }
57
+ overrides.support_threshold_angle = String(threshold);
58
+ }
36
59
  return Object.keys(overrides).length ? overrides : undefined;
37
60
  }
38
61
 
@@ -0,0 +1,126 @@
1
+ /**
2
+ * MCP tool annotations (spec 2025-03-26 and later), one entry per tool, chosen from
3
+ * what the tool's handler actually does. Clients and Counterpart's remote endpoint
4
+ * read them to decide which tools a device may call, so every listed tool must have
5
+ * one (tests/tool-annotations.test.mjs).
6
+ *
7
+ * readOnlyHint: changes nothing outside this server (printer, files, other apps).
8
+ * destructiveHint: may delete, overwrite, end or irreversibly change something.
9
+ * idempotentHint: repeating the call with the same arguments has no further effect.
10
+ * openWorldHint: reaches something outside this server and its files: the printer,
11
+ * Bambu Cloud, a remote slicer, or another application (Blender, Fusion, Bambu Connect).
12
+ */
13
+ export interface ToolAnnotations {
14
+ readOnlyHint: boolean;
15
+ destructiveHint: boolean;
16
+ idempotentHint: boolean;
17
+ openWorldHint: boolean;
18
+ }
19
+
20
+ const hints = (readOnlyHint: boolean, destructiveHint: boolean, idempotentHint: boolean, openWorldHint: boolean): ToolAnnotations =>
21
+ ({ readOnlyHint, destructiveHint, idempotentHint, openWorldHint });
22
+
23
+ /** Reads the printer or another outside system; changes nothing. */
24
+ const READ_OUTSIDE = hints(true, false, true, true);
25
+ /** Reads local files or this server's configuration only. */
26
+ const READ_LOCAL = hints(true, false, true, false);
27
+ /** Writes a fixed-name output into this server's temporary directory, replacing an earlier output of that name; inputs untouched. */
28
+ const LOCAL_OUTPUT = hints(false, true, true, false);
29
+ /** Sets a printer setting to a given value; setting it again changes nothing. */
30
+ const SET_PRINTER = hints(false, false, true, true);
31
+ /** Starts a print job: adds a job, removes nothing, but a repeat would start another. */
32
+ const START_PRINT = hints(false, false, false, true);
33
+ /** Starts a print, auto-slicing an unsliced project first, which replaces an earlier slice output of that name. */
34
+ const SLICE_AND_PRINT = hints(false, true, false, true);
35
+
36
+ export const TOOL_ANNOTATIONS: Record<string, ToolAnnotations> = {
37
+ // Printer and cloud reads
38
+ get_printer_status: READ_OUTSIDE,
39
+ get_printer_filaments: READ_OUTSIDE,
40
+ resolve_3mf_ams_slots: READ_OUTSIDE, // reads the live AMS inventory
41
+ list_printer_files: READ_OUTSIDE,
42
+ counterpart_print_progress: READ_OUTSIDE,
43
+ // connect: true starts the bridge agent, which writes its configuration and device identity and can replace certificates.
44
+ bambu_network_bridge_status: hints(false, true, true, true),
45
+ camera_frame: READ_OUTSIDE,
46
+ // Open (or renew) and close the one camera connection all viewers of this printer share; no printer motion or commands.
47
+ camera_stream_start: hints(false, false, true, true),
48
+ camera_stream_stop: hints(false, false, true, true),
49
+ // Writes save_path, overwriting an existing file there; every call takes a new frame.
50
+ camera_snapshot: hints(false, true, false, true),
51
+
52
+ // Local reads
53
+ inspect_print_file: READ_LOCAL,
54
+ list_3mf_plate_objects: READ_LOCAL,
55
+ get_stl_info: READ_LOCAL,
56
+ list_templates: READ_LOCAL,
57
+ get_slice_settings: LOCAL_OUTPUT, // a 3MF's settings are extracted to a fixed file in the temporary directory
58
+ counterpart_printer_info: READ_LOCAL, // configuration and capabilities; sends nothing to the printer
59
+
60
+ // Local outputs in the server's temporary directory
61
+ extend_stl_base: LOCAL_OUTPUT,
62
+ scale_stl: LOCAL_OUTPUT,
63
+ rotate_stl: LOCAL_OUTPUT,
64
+ merge_vertices: LOCAL_OUTPUT,
65
+ center_model: LOCAL_OUTPUT,
66
+ lay_flat: LOCAL_OUTPUT,
67
+ // Same, but a configured orca-slicer-api slices on a remote service, a new job and output each call.
68
+ slice_stl: hints(false, true, false, true),
69
+ slice_with_template: hints(false, true, false, true),
70
+ // New 3MF at a caller-chosen path; never overwrites, so a repeat fails and changes nothing.
71
+ counterpart_make_3mf: hints(false, false, true, false),
72
+ // Copies into the template registry, replacing a template of the same name.
73
+ save_template: hints(false, true, true, false),
74
+ // Replaces BAMBU_DEFAULT_CONNECTION_MODE/TYPE in .env and in this process.
75
+ counterpart_print_route: hints(false, true, true, false),
76
+
77
+ // Print starts
78
+ start_print: START_PRINT,
79
+ start_print_job: START_PRINT,
80
+ print_3mf: SLICE_AND_PRINT,
81
+ print_3mf_bambu_network: SLICE_AND_PRINT,
82
+ print_collar_charm: SLICE_AND_PRINT,
83
+ upload_file: START_PRINT, // print: true starts the uploaded G-code; uploads never overwrite (unique names)
84
+ upload_gcode: hints(false, false, false, true), // a uniquely named new copy per call
85
+
86
+ // Print controls
87
+ pause_print: SET_PRINTER,
88
+ resume_print: SET_PRINTER,
89
+ cancel_print: hints(false, true, true, true), // ends the job; it cannot be resumed
90
+ skip_objects: hints(false, true, true, true), // skipped objects are not printed and cannot be restored
91
+
92
+ // Printer settings
93
+ set_print_speed: SET_PRINTER,
94
+ set_airduct_mode: SET_PRINTER,
95
+ set_temperature: SET_PRINTER,
96
+ set_fan_speed: SET_PRINTER,
97
+ set_light: SET_PRINTER,
98
+ set_ams_drying: SET_PRINTER,
99
+ reread_ams_rfid: hints(false, false, false, true), // moves AMS filament on every call
100
+ // Replaces stored AMS metadata or the calibration selection on an X2D.
101
+ x2d_native_control: hints(false, true, true, true),
102
+ clear_hms_errors: hints(false, true, true, true), // clears the printer's error record
103
+ delete_printer_file: hints(false, true, true, true),
104
+ // Only handshake and sign-in reads are allowed, but with_agent (the default) starts the bridge agent like the status probe.
105
+ bambu_network_call: hints(false, true, true, true),
106
+ // Opens the file in the Bambu Connect app; does not print.
107
+ bambu_connect_import_file: hints(false, false, false, true),
108
+
109
+ // Blender and Fusion
110
+ blender_mcp_status: READ_OUTSIDE, // connects and lists tools; edits nothing
111
+ blender_mcp_call: hints(false, true, false, true), // any Blender tool, including execute_blender_code
112
+ // The standard route preserves scene objects and needs a new output path; a configured legacy bridge promises neither.
113
+ blender_mcp_edit_model: hints(false, true, false, true),
114
+ fusion_mcp_status: hints(false, false, true, true), // launch: true starts Fusion on this computer
115
+ fusion_mcp_call: hints(false, true, false, true), // any Fusion tool, including execute_code
116
+ fusion_mcp_new_design: hints(false, false, false, true), // opens another new document
117
+ fusion_mcp_export: hints(false, false, true, true), // never overwrites; a repeat fails and changes nothing
118
+ };
119
+
120
+ /** Assumed for a tool missing from the table (a bug the tests catch): the least a client should trust it. */
121
+ const UNKNOWN = hints(false, true, false, true);
122
+
123
+ /** The tool with its annotations. */
124
+ export function withAnnotations<T extends { name: string }>(tool: T): T & { annotations: ToolAnnotations } {
125
+ return { ...tool, annotations: TOOL_ANNOTATIONS[tool.name] ?? UNKNOWN };
126
+ }