bambu-printer-mcp 1.1.52 → 1.1.53

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/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";
@@ -2592,7 +2593,6 @@ class BambuPrinterMCPServer {
2592
2593
  {
2593
2594
  name: "inspect_print_file",
2594
2595
  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
2596
  inputSchema: {
2597
2597
  type: "object",
2598
2598
  additionalProperties: false,
@@ -2817,8 +2817,7 @@ class BambuPrinterMCPServer {
2817
2817
  bambu_token: { type: "string", description: "Access token (default: value from env); never returned." }
2818
2818
  }
2819
2819
  },
2820
- outputSchema: PRINTER_INFO_OUTPUT_SCHEMA,
2821
- annotations: { readOnlyHint: true }
2820
+ outputSchema: PRINTER_INFO_OUTPUT_SCHEMA
2822
2821
  },
2823
2822
  {
2824
2823
  name: "counterpart_print_route",
@@ -2843,8 +2842,7 @@ class BambuPrinterMCPServer {
2843
2842
  bambu_token: { type: "string", description: "Access token (default: value from env)" }
2844
2843
  }
2845
2844
  },
2846
- outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA,
2847
- annotations: { readOnlyHint: true }
2845
+ outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA
2848
2846
  },
2849
2847
  {
2850
2848
  name: "counterpart_make_3mf",
@@ -2934,7 +2932,7 @@ class BambuPrinterMCPServer {
2934
2932
  },
2935
2933
  outputSchema: FUSION_EXPORT_OUTPUT_SCHEMA
2936
2934
  }
2937
- ]
2935
+ ].map(withAnnotations)
2938
2936
  };
2939
2937
  });
2940
2938
  this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
@@ -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.53",
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";
@@ -3125,7 +3126,6 @@ class BambuPrinterMCPServer {
3125
3126
  {
3126
3127
  name: "inspect_print_file",
3127
3128
  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
3129
  inputSchema: {
3130
3130
  type: "object",
3131
3131
  additionalProperties: false,
@@ -3350,8 +3350,7 @@ class BambuPrinterMCPServer {
3350
3350
  bambu_token: { type: "string", description: "Access token (default: value from env); never returned." }
3351
3351
  }
3352
3352
  },
3353
- outputSchema: PRINTER_INFO_OUTPUT_SCHEMA,
3354
- annotations: { readOnlyHint: true }
3353
+ outputSchema: PRINTER_INFO_OUTPUT_SCHEMA
3355
3354
  },
3356
3355
  {
3357
3356
  name: "counterpart_print_route",
@@ -3376,8 +3375,7 @@ class BambuPrinterMCPServer {
3376
3375
  bambu_token: { type: "string", description: "Access token (default: value from env)" }
3377
3376
  }
3378
3377
  },
3379
- outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA,
3380
- annotations: { readOnlyHint: true }
3378
+ outputSchema: PRINT_PROGRESS_OUTPUT_SCHEMA
3381
3379
  },
3382
3380
  {
3383
3381
  name: "counterpart_make_3mf",
@@ -3467,7 +3465,7 @@ class BambuPrinterMCPServer {
3467
3465
  },
3468
3466
  outputSchema: FUSION_EXPORT_OUTPUT_SCHEMA
3469
3467
  }
3470
- ]
3468
+ ].map(withAnnotations)
3471
3469
  };
3472
3470
  });
3473
3471
 
@@ -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
+ }