Snapshot of the current OrcaSlicer session: app and project info, the active print/filament/printer presets with which of their keys are modified (dirty), whether the last slice is still valid, and whether a slice is running. Read-only.

Call it first to orient before slicing or editing, to see which settings drift from their preset, or to check slice_result_valid before trusting earlier stats.

Read merged config values (optionally filtered to keys).

Apply config changes to the active project as unsaved overrides, atomically: if any key is invalid the whole batch is rejected and nothing changes. Returns {applied, errors}.

Overrides show as modified in get_status, are not written to any preset file, and revert if the preset is reselected; call save_preset to persist them. Each apply invalidates the last slice, so re-slice afterwards. It does not run the physics gate, so for temperature, speed, acceleration, or flow keys run check_profile_physics before trusting the result. To edit a stored preset rather than the live project, use edit_preset.

On a multi-filament setup do filament edits before print edits: changing another slot's value means select_preset for that slot, which discards unsaved print overrides (docs/order-of-operations.md).

Start slicing the current plate in the background and return immediately, without waiting for the result. The reply is 'started' (a slice began), 'already_valid' (the plate is unchanged and the last result still holds), or a conflict if a slice is already running.

Fire-and-forget: poll get_slice_status for progress and stats, or cancel_slice to stop it. Prefer slice_and_wait when you want the finished stats back in one call.

State of the current or most recent slice: state (slicing, done, error, or idle), stats (print time and filament use when done), and any warnings or errors. Read-only.

Poll this after slice to follow progress and read the result; 'idle' means no slice has run or it was cancelled. For only the pass/fail warnings use get_slice_warnings; for a per-feature time and filament breakdown use get_slice_breakdown.

Just the warnings/errors from the last (or current) slice, plus validity: the fast 'did anything go wrong' check and the way to confirm a fix cleared.

NOTE: only as complete as the API exposes. On the current fork build this may report valid with an empty warnings list even when the GUI shows a plate-boundary toast - the fork must populate the plater warning list (tracked as the fork batch). Once it does, this reports the real warnings with no change here.

Per-feature breakdown of the last slice + a stateless predicted-vs-observed flow check.

Returns per-role time/filament + speed/flow ranges, global time-weighted metric distributions, per-layer aggregates, and a prediction_check flagging where the profile's speed was silently throttled at the flow ceiling ('clamped'). Answers 'which feature is the time hog' directly instead of by trial slicing.

Degrades to {"available": false, "reason": ...} on fork builds that don't emit the breakdown, or when there is no valid slice.

Abort a running slice, or unwedge a stale 'slicing' state (e.g. after an object outside the bed). Safe when idle.

Slice the current plate and block until it finishes, then return the final stats and warnings in one call. If the plate is already sliced and unchanged, it returns the existing result without re-slicing.

This is the usual way to slice when you want the outcome immediately. For a non-blocking start, use slice then poll get_slice_status; to sweep one setting across values, use compare_settings.

Apply config overrides and then slice in one step, returning {applied, errors, result} with the resulting stats and warnings. The changes are atomic (any invalid key rejects the whole batch) and unsaved, exactly like set_config, so they revert if the preset is reselected.

Use this to test the effect of a tweak in a single call. Use set_config then slice_and_wait to keep the steps separate, or compare_settings to try several values of one key.

For each value of key, slice and collect stats/warnings; restore the original when done.

Non-destructive: the original value of key is put back even on error.

Slice the current plate under several named variants and compare the cost of each.

Each variant is {"name": str, "changes": {setting: value}}; changes={} means the current config as-is (a natural baseline row). Applies each variant over the ORIGINAL config (resetting between variants, so they don't stack), slices it, then restores your config exactly as it was - nothing is left changed (slice validity is left false, as after any un-resliced edit).

Returns a ready-to-relay headline and table_markdown, plus structured variants. All deltas and percentages are ALREADY computed and rounded against baseline (defaults to the changes={} variant, else the first) - relay them as given rather than recomputing. recommended names one pick; recommended_is_dominant says whether it beats every variant on every axis (time, filament, warnings) or is only the fastest warning-free option amid a genuine trade-off (tradeoff then names the frontier).

Each variant is a full slice (minutes); capped at 8. Set detail=True only when a per-feature (wall/infill/support) split is wanted - it grows the response ~N x. With more than ~5 variants, lead with the recommendation and the extremes, not all rows.

List objects in the project: id (stable), name, size_mm, transform (offset/rotation/scale) and, on fork v2.4.2-mcp.13 and later, the 0-based plate each one sits on (-1 when it is off every plate).

Set per-object config overrides on an object by id, e.g. {"wall_loops": 4, "sparse_infill_density": "30%"}. Atomic (nothing applied if any key is invalid).

Duplicate an object on the plate by id (adds a copy, offset from the original).

Remove one object from the current plate by id. This is permanent within the session and cannot be undone through the API; the other objects keep their ids.

Call list_objects first to get the id. Deleting leaves the last slice invalid, so re-slice afterwards. To drop just one copy made with duplicate_object, pass that copy's id.

Move/rotate/scale an object by id. translate=[dx,dy,dz] mm (relative), rotate=[rx,ry,rz] degrees (relative), scale=[sx,sy,sz] absolute factor. Provide at least one.

On fork v2.4.2-mcp.13 and later the object then belongs to whichever plate it sits on, as after a drag in the window; list_objects shows the plate. To send an object to another plate, move_object_to_plate is simpler than working out coordinates.

Auto-arrange all objects on the plate (async job; poll get_job_status until idle).

With several plates this is OrcaSlicer's "Arrange all": it re-packs the objects of every unlocked plate together and deletes plates left empty at the end, which undoes a one-part-per-plate layout. To shift one object, use transform_object instead.

Auto-orient all objects for printing (async job; poll get_job_status until idle).

List the plates in the project: each one's 0-based index, name, whether it is the current plate (the one slice, get_gcode, render_plate and get_job_status act on), lock state, build volume and the objects it holds. Also says how many plates the build allows (max) and whether one can be added or deleted right now. Read-only.

Plate numbers shown in the OrcaSlicer window are 1-based; every tool here takes the 0-based index from this list. Needs fork v2.4.2-mcp.13 or later.

Add an empty plate to the project, the same way the toolbar's "Add plate" button does. Returns the new plate's 0-based index for move_object_to_plate and select_plate.

Use it when parts should print separately: load them, add a plate, move the second part across with move_object_to_plate, then select_plate and slice each one. A plate cannot be added while a slice is running (409) or at the build's plate limit (422).

Make a plate the current one, exactly like clicking it: slice_and_wait, get_gcode, render_plate, get_slice_status and get_job_status then act on that plate.

get_slice_status then reports that plate's own result: its stats if it is still sliced, otherwise idle with "plate N is not sliced". Switching plates leaves unsaved config overrides alone; it changes only which plate is sliced. Selecting the plate that is already current is a no-op.

Delete a plate. The objects it held are NOT deleted: OrcaSlicer parks them beside the bed, as the toolbar's delete does, and the reply says how many were moved off-plate (objects_moved_off_plate). Use move_object_to_plate to put them somewhere printable. OrcaSlicer parks them where the next plate appears, so an add_plate straight after a delete picks them back up.

The only plate cannot be deleted (422 last_plate). Call list_plates first for the index; this cannot be undone through the API.

Move an object onto another plate. Coming from a plate it keeps its position relative to that plate (front-left of plate 1 lands front-left of plate 2); coming from off-plate (parked beside the bed) it lands at the destination's centre. If it then overlaps a part, shift it with transform_object; arrange_plate would re-pack every plate together.

list_objects reports each object's plate (-1 when off every plate). Moving leaves both plates' slices invalid, so re-slice. An object already on that plate is left where it is (moved: false); a locked plate at either end refuses the move (plate_locked).

Whether the plate's background job worker is idle or still running. Read-only.

arrange_plate and auto_orient start async jobs; poll this until it reports idle before you read object positions or slice, so you act on the settled layout rather than a mid-move state.

Collect live events (slice.*/config.changed/project.opened) over a bounded window.

Find config keys containing substring (helps discover among the ~600 keys).

One-call plate diagnosis: app/slice status, objects on the plate, bed + active skirt/brim/clearance settings, and the last slice's warnings, so you don't have to chain status->objects->config. Start here for 'why won't this slice / fit'.

Slice warnings are only as complete as the fork exposes today (see get_slice_warnings). For a 'does it fit the bed' estimate, pair with check_placement.

Estimate whether every object (plus its skirt/brim ring) fits inside the printable area. Returns per-object fit, expanded first-layer bbox, per-edge clearance (mm), and overflow.

APPROXIMATE: uses the object footprint from size+offset, not the sliced toolpath (skirt arcs, half-line-width, travel/wipe excluded); single-instance objects only. At ~mm margins the true verdict needs get_slice_warnings - this is a fast first-pass.

Retrieve curated slicing knowledge + saved context notes for a topic, symptom, or intent. ALWAYS call before deriving or changing settings for a user goal. Composes principles per situation, never returns preset bundles. Falls back to find_config_keys/web search if empty.

When recommending, present 2-3 concrete options quantified with predicted print time and filament mass from real slice results (slice + status tools) - never adjectives alone.

Deterministic pre-save gate: fetches the live config, overlays optional proposed changes, and runs flow/temperature/geometry/cooling math. RUN THIS BEFORE save_preset. verdict=blocked means DO NOT SAVE.

Persist a context fact for future sessions. scope: 'machine:/', 'user', or 'project:'. Local plain files; user-readable and deletable.

Authoritative definition of one OrcaSlicer setting: label, tooltip, type, unit, valid range, enum values, and default. Read-only and offline, so it works even when OrcaSlicer is not running.

Use it to learn a setting's exact type and allowed values before writing it with set_config or edit_preset. To find candidate keys by keyword first, use search_settings.

Search settings by keyword across key/label/tooltip; returns compact matches (key, label, category, short tooltip), ranked key/label first. Offline.

Load a model file (path on the OrcaSlicer host) onto the current plate. Accepts .stl/.obj/.3mf, plus .step/.stp on fork v2.3.2-mcp.3+. Large STEP files can take a minute to tessellate; the call waits.

Make the named preset the active one for its group (print, filament, or printer).

Discards unsaved overrides in EVERY preset group, not just the one being switched: a filament switch also drops unsaved print and printer edits, including ones made by hand in the OrcaSlicer window. That is deliberate (OrcaSlicer consults the other groups when switching, and any unsaved one would open a modal dialog nothing can dismiss remotely), so call save_preset first if any unsaved edit should survive. Newer slicer builds report which groups were affected as 'discarded_changes' in the reply.

This also makes it the canonical way to reset dirty config. It leaves the last slice invalid, so re-slice afterwards. Use list_presets for valid names. Because of this, make filament selections and edits before print-group edits (docs/order-of-operations.md).

Save the currently edited settings as a named user preset (create or update, visible in the GUI immediately). type = print|filament|printer. detach=True saves it standalone instead of inheriting the current base preset; use it when creating a filament preset for a DIFFERENT material than the one selected, otherwise the new preset inherits the base's filament_type and temperatures.

Run check_profile_physics first; do not save when verdict=blocked.

List print/filament/printer presets with system/selected/visible flags.

F12: by default returns only USER presets plus whatever is currently SELECTED - the built-in system presets are ~400 entries of noise. Pass include_system=True for the full list, and/or type='print'|'filament'|'printer' to restrict to one category. hidden_system reports how many system presets were filtered out.

Variable layer height for one object. mode='adaptive' (quality 0..1, higher = finer detail) generates an adaptive profile; mode='reset' (aliases: 'default', 'none') restores uniform layers.

Override the layer height over a Z band of one object (e.g. 0 to 5 mm printed at 0.1 mm for finer detail near the base). Passing the same min_z and max_z again updates that band's height; clear=True removes every band on the object.

Bands are per-object and invalidate the last slice, so re-slice afterwards. For a single height across the whole object use set_layer_height instead. Get the id from list_objects.

Read the full settings of a named preset without selecting it. type = print|filament|printer.

Delete a USER preset (system presets and the currently-selected one are refused). type = print|filament|printer.

Edit a named preset's settings and persist them: selects it, applies the changes atomically, saves under the same name. Runs the check_profile_physics gate first (F15) and refuses with error=physics_blocked if the changes would INTRODUCE a failing physics check (pre-existing failures do not block unrelated edits). For type='filament', checks that also depend on the currently selected PRINT preset (flow_ceiling, temp_vs_flow) do not block; they come back as cross_layer_warnings, because a filament preset pairs with many print presets.

Rename a user preset by copying it to new_name, selecting the copy, and deleting the original. Only user presets can be renamed; system presets are read-only.

Because it selects the renamed preset, this leaves it active and discards unsaved config overrides, the same as select_preset, and leaves the last slice invalid, so re-slice afterwards.

Retrieve the last successful slice's G-code as text.

Machine-readable plate facts from the last slice's G-code, per object, so you can answer orientation and placement questions instead of guessing from Euler angles or a picture: how the part stands (flat / tilted / on an edge or corner, from first-layer contact versus its widest layer), the first-layer footprint as islands, where overhang extrusions concentrate by 10 mm height band, where support stands and where its interface touches the part, and which side the outer-wall seams sit on (checked against seam_position). Each object gets a server-written summary sentence; relay it rather than recomputing. Read-only. Needs a valid slice; returns {"error": "not_sliced"} otherwise. Copies of one object are aggregated (Orca labels every copy 0); footprint islands still show per-copy contact. The parsed result is cached per slice (the G-code itself is still downloaded each call to detect a new slice). All bboxes are [x0, y0, x1, y1] in plate millimetres.

Save the last successful slice's G-code and record the slice (model, a fingerprint of the objects' names and sizes, full settings snapshot, and OrcaSlicer's time and filament estimates) in the local outcome store under that filename. When that file is printed, list_print_history (or klipper-mcp's recorder) matches the finished job by filename, so the real result joins back to these settings. Returns the saved path; hand it to klipper-mcp's start_print. Default filename: _.gcode. Never overwrites an existing file: a name collision gets a -2, -3, ... suffix. Writes into a gcode folder under PRINT_OUTCOMES_DIR if set, else under the shared print-outcomes folder (~/projects/_shared/print-outcomes) if it already exists, else under ~/.orcaslicer-mcp; the folder is created if missing. If the store write fails, the file is still saved and outcome_recorded is False.

How did past prints of THIS model actually turn out? Matches the current plate by geometry (or by model_name if given / the slicer is offline), returning each past print's result (success/cancelled/error), your recorded verdict (e.g. 'warped'), and the settings it was sliced with. Call this BEFORE slicing and tell the user anything relevant (a past warp, a failed layer height). Each row also carries failure_reason (the printer's own words, when known) and the slicer's estimates (est_time_s, est_filament_g). duration_s is Moonraker's whole job time, including heating up and any pauses, so beside the estimates it overstates an overrun; list_print_history compares the print time (without heating or pauses) with the estimate. filament_g comes from the G-code file's own estimate, because printers don't report grams. Call list_print_history first to pull in recent results. Read-only. Returns available=false and nothing else when no outcome store exists yet. If neither geometry nor name matches, it returns the most recent prints of ANY model with matched_by='recent'; never attribute those to the current model.

Render a PNG picture of the current plate so you can SEE it.

view="editor": the models on the bed BEFORE slicing - use to check orientation, plate contact, and first-layer footprint (an Euler triple is near-unreadable; this is the ground truth). view="preview": the sliced toolpaths colored by feature role AFTER a successful slice - support is visibly distinct, so use it to check where support actually went. angle: iso|top|front|left|right|rear|bottom. frame: "plate" zooms out to the whole bed (where the part sits, footprint), "object" zooms in on the model/toolpaths (detail). Defaults to "plate" for the editor view and "object" for the preview view; pass it explicitly when a side view of a small part would otherwise be a speck on a big bed.

What the 3D printer is doing right now: state (idle, heating, printing, paused, finished, cancelled, error, shutdown, offline), nozzle and bed temperatures with their targets, the current job (file, progress, layer, time elapsed and left, and what the time left is based on), and any problems the printer reports, each in the printer's own words with a plain-English hint for common ones. Relay headline as-is. Never invent a cause the printer did not report.

Finds the printer from OrcaSlicer's active printer profile (or ORCA_PRINTER_URL), so it needs no extra setup once the printer is connected in OrcaSlicer. Klipper (Moonraker) printers report the most; OctoPrint reports basic status. Read-only: it never sends commands to the printer.

Wait until the printer reaches a point in a print, checking every 5 seconds. Returns as soon as it happens (met: true), or at the timeout with the latest status (met: false). It also returns early, with stopped_early saying why, when the printer reports a fault, when the job ends before the point it waits for (a cancelled print, say), or after losing contact ("Lost contact with the printer"). A job that completes successfully while the wait is for 'printing' or 'first_layer_done' counts as met (a one-layer print passes both at once). A met result can carry stopped_early too, for example a job that finished with an error. Waiting for 'finished' when nothing is printing returns at once with the note 'nothing is printing'. Read-only: it never sends commands.

How did recent prints on the printer actually end? For each finished job: result (success, cancelled or error), how long it took against the slicer's estimate, filament used, and for failed or stopped jobs the printer's own reason while its console still holds it. summary says how the slicer's time estimates compare with reality once there are a few finished prints. Also copies those jobs into the local outcome store (safe to repeat), so recall_prints can learn from them. Klipper printers only. limit is capped at 50.

Does the active OrcaSlicer profile match the printer it will print on? Compares nozzle size, bed size and height, the highest speeds and accelerations, nozzle and bed temperatures, and firmware retraction against the printer's own Klipper settings. Each check comes back ok, warn or unknown with both values and why it matters; relay headline and the warnings. Warnings only: it never changes or blocks anything. Run it before printing with a new or edited profile, or when prints take longer than estimated. Klipper printers only; needs OrcaSlicer running.