Calculate the bounding box of a CAD file.

Args: input_file (str): The path of the CAD file. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive)

Returns: dict | str: A dictionary with 'center' (dict with x,y,z) and 'dimensions' (dict with x,y,z), or an error message if the operation fails.

Calculate physical properties (volume, mass, surface area, center of mass, bounding box) of a CAD file.

Args: input_file (str): The path of the file. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive) unit_length (str): The unit of length for center of mass. One of 'cm', 'ft', 'in', 'm', 'mm', 'yd'. unit_mass (str): The unit of mass for the mass result. One of 'g', 'kg', 'lb'. unit_density (str): The unit of density for the material. One of 'lb:ft3', 'kg:m3'. density (float): The density of the material. unit_area (str): The unit of area for surface area. One of 'cm2', 'dm2', 'ft2', 'in2', 'km2', 'm2', 'mm2', 'yd2'. unit_volume (str): The unit of volume. One of 'cm3', 'ft3', 'in3', 'm3', 'mm3', 'yd3', 'usfloz', 'usgal', 'l', 'ml'.

Returns: dict | str: A dictionary with keys 'volume', 'mass', 'surface_area', 'center_of_mass', and 'bounding_box', or an error message if the operation fails.

Calculate the center of mass of a 3d object represented by the input file.

Args: input_file (str): The path of the file to get the mass from. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive) unit_length (str): The unit of length to return the result in. One of 'cm', 'ft', 'in', 'm', 'mm', 'yd'

Returns: str: The center of mass of the file in the specified unit of length, or an error message if the operation fails.

Calculate the mass of a 3d object represented by the input file.

Args: input_file (str): The path of the file to get the mass from. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive) unit_mass (str): The unit of mass to return the result in. One of 'g', 'kg', 'lb'. unit_density (str): The unit of density to calculate the mass. One of 'lb:ft3', 'kg:m3'. density (float): The density of the material.

Returns: str: The mass of the file in the specified unit of mass, or an error message if the operation fails.

Calculate the surface area of a 3d object represented by the input file.

Args: input_file (str): The path of the file to get the surface area from. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive) unit_area (str): The unit of area to return the result in. One of 'cm2', 'dm2', 'ft2', 'in2', 'km2', 'm2', 'mm2', 'yd2'.

Returns: str: The surface area of the file in the specified unit of area, or an error message if the operation fails.

Calculate the volume of a 3d object represented by the input file.

Args: input_file (str): The path of the file to get the volume from. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive) unit_volume (str): The unit of volume to return the result in. One of 'cm3', 'ft3', 'in3', 'm3', 'mm3', 'yd3', 'usfloz', 'usgal', 'l', 'ml'.

Returns: str: The volume of the file in the specified unit of volume, or an error message if the operation fails.

Point the camera at the current "selection set".

Useful for making a small selection legible, especially an edge: an edge is only a pixel or two wide, so centring it helps far more than any change of colour. Set the selection first with select_entities.

Centring moves the camera without re-framing the scene, so parts of the model may fall outside the image. Follow with snapshot passing zoom=False, since zoom=True re-frames the whole scene and undoes the centring.

Args: session_id: An open modeling session, from start_modeling_session. Required: camera position is scene state and would be discarded without one. move_vantage: Move the camera's vantage point as well as its target. True (the default) centres the selection most precisely; False re-aims the camera from where it already is.

Returns: DefaultCameraCenterToSelection: Confirmation that the camera was centred.

Convert a CAD file from one format to another CAD file format.

Args: input_file (str): The input cad file to convert. The file should be one of the supported formats: .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, .stl (case-insensitive) export_path (str | None): The path to save the converted CAD file to. If the path is a directory, a temporary file will be created in the directory. If the path is a file, it will be overwritten if the extension is valid. export_format (str | None): The format of the exported CAD file. This should be one of 'fbx', 'glb', 'gltf', 'obj', 'ply', 'step', 'stl'. If no format is provided, the default is 'step'.

Returns: str: The path to the converted CAD file, or an error message if the operation fails.

Get the start and end points of a curve entity.

Args: curve_id: Curve UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: CurveGetEndPoints: The curve's start and end points.

Get whether a curve is a line, arc, or NURBS curve.

Args: curve_id: Curve UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: CurveGetType: The curve's geometric type.

Get the length of an edge entity in the current scene units.

Args: edge_id: Edge UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: EdgeGetLength: The edge length in the current scene units.

Evaluate a serialized KCL path at parameter t.

Examples of path_json:

{
  "start": {
    "from": [10, 0]
  },
  "value": [
    {
      "type": "Arc",
      "center": [0, 0],
      "radius": 10,
      "angle_range": [0, 90]
    }
  ]
}

{
  "start": {
    "from": [0, 0]
  },
  "value": [
    {
      "type": "ToPoint",
      "to": [10, 0]
    },
    {
      "type": "ToPoint",
      "to": [10, 10]
    }
  ]
}

Args: path_json: The serialized JSON representation of the KCL sketch or path. t: Normalized path parameter, conventionally between 0 and 1. session_id: A modeling session populated by execute_kcl.

Returns: EngineUtilEvaluatePath: The position on the path at parameter t.

Get the minimum and maximum distance between two model entities.

Args: entity_id1: The first entity UUID, typically obtained from an artifact graph. entity_id2: The second entity UUID. session_id: A modeling session populated by execute_kcl. on_axis: Optional global axis for projected distance; omit for Euclidean distance.

Returns: EntityGetDistance: The minimum and maximum distance between the entities.

Get all child UUIDs belonging to an entity.

Args: entity_id: Entity UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: EntityGetAllChildUuids: All child entity UUIDs.

Get an entity's index within its parent.

Args: entity_id: Entity UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: EntityGetIndex: The entity's index within its parent.

Get the UUID of an entity's parent.

Args: entity_id: Entity UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: EntityGetParentId: The parent entity's UUID.

Get the sketch path UUIDs belonging to an entity.

Args: entity_id: Entity UUID, typically obtained from an artifact graph. session_id: A modeling session populated by execute_kcl.

Returns: EntityGetSketchPaths: The sketch path UUIDs belonging to the entity.

Execute KCL once and collect requested measurements, snapshots and exports.

Prefer this when several checks or final export formats are known in advance. Provide exactly one source: self-contained kcl_code or a saved kcl_path project. Save editable source separately; inline code does not create a source file. Mock errors prevent hosted execution. The isolated session closes after the operation; no persistent session ID is needed or returned.

snapshot_request: Optional views (1–4 named views or camera dicts with up, vantage, center). An empty object requests one isometric image. Named views use zoom-to-fit; custom views default to their explicit framing. physical_properties_request: Optional properties list (volume, mass, surface_area, center_of_mass, bounding_box) and units. Mass additionally requires density and unit_density. Only requested properties are measured. exports: Optional format/destination_dir pairs. Each format needs a separate, non-overlapping directory, created if missing. Returned bundle filenames are preserved; existing files are not overwritten. Request final formats together rather than executing separately for each export.

Returns structured execution/inspection outcomes and per-export statuses and file paths, plus an inline image when requested and available. ok describes execution only: inspect output statuses for partial failures. Output failures never rerun geometry; successful outputs remain available.

Execute KCL code given a string of KCL code or a path to a KCL project. Either kcl_code or kcl_path must be provided. If kcl_path is provided, it should point to a .kcl file or a directory containing a main.kcl file.

Prefer evaluate_kcl when execution, measurements, snapshots, or exports are needed together; it collects them from one execution.

Executing kcl_code does not save a .kcl source file. For model creation, save the source and required project files with the client's authorized file-editing tools, then validate the saved project using kcl_path and include the editable KCL files in the handoff.

Session executions save the artifact graph to a temporary JSON file and return its path. Local executions do not produce an artifact graph and can have large network overhead depending on the model.

Args: kcl_code (str | None): Self-contained KCL code to execute. Standard-library imports are allowed; filesystem imports require kcl_path. kcl_path (str | None): The path to a KCL file to execute. The path should point to a .kcl file or a directory containing a main.kcl file. Dependencies and symlink targets must remain inside the entrypoint's directory. session_id: An open modeling session in which to execute the KCL.

Returns: ResultZooExecuteKcl: Separate mock_preflight and real_execution outcomes, each with status, message, and diagnostics. Mock errors return immediately with real_execution not_run; mock warnings remain visible and allow real execution. Known mock-engine limitations are warnings. Session successes include path_artifact_graph. Transient local failures may retry real execution without repeating preflight.

Format KCL code given a string of KCL code or a path to a KCL project. Either kcl_code or kcl_path must be provided. If kcl_path is provided, it should point to a .kcl file or a directory containing .kcl files.

Args: kcl_code (str | None): The KCL code to format. kcl_path (str | None): The path to a KCL file to format. The path should point to a .kcl file or a directory containing a main.kcl file.

Returns: str | None: Returns the formatted kcl code if the kcl_code is used otherwise returns None, the KCL in the kcl_path will be formatted in place

Get the position, gradient, normal, and center of a face in a modeling session.

Args: face_id (str): Usually a user or LLM-selected face id. session_id: A modeling session populated by execute_kcl.

Returns: FaceInfo: The face position, gradient, normal, and center. The position is the starting point of the face's outside perimeter in KittyCAD engine space. The center is the geometric center of the face and should generally be preferred over the position.

Get the full content of a specific KCL documentation file.

Prefer lookup_kcl_docs first; fetch a full page when more detail is needed. Use list_kcl_docs() to see available documentation paths, or lookup_kcl_docs() to find relevant documentation by symbol or topic.

Args: doc_path (str): The path to the documentation file (e.g., "docs/kcl-lang/functions" or "docs/kcl-std/functions/std-sketch-extrude")

Returns: str: The full Markdown content of the documentation file, or an error message if not found.

Raises: ToolError: Documentation could not be fetched; the call can be retried.

Get the full content of a specific KCL sample including all files.

Downloads a public Aquarium project and retrieves its KCL files with their project-relative paths, including files in subdirectories.

Use list_kcl_samples() to see available sample names, or search_kcl_samples() to find samples by keyword.

Args: sample_name (str): The public project ID returned by list_kcl_samples() or search_kcl_samples().

Returns: SampleData | str: A SampleData dictionary containing: - name: The public project ID - title: Human-readable title - description: Brief description - multipleFiles: Whether the sample contains multiple files. Reliable here (unlike in list_kcl_samples / search_kcl_samples), because this tool downloads the project and counts its KCL files. - files: List of SampleFile dictionaries, each with a project-relative 'filename' and its 'content' Returns an error message string if the sample is not found.

Raises: ToolError: The sample could not be fetched; the call can be retried.

List modeling sessions owned by the current MCP server process.

Use this to recover the active session ID after reconnecting to a server process. A restarted server has no sessions. The current implementation supports at most one session, but the list return type allows future support for multiple sessions.

Returns: list[str]: Active modeling session IDs, currently empty or one item.

Execute KCL and return a report of sketch constraint status. Either kcl_code or kcl_path must be provided. If kcl_path is provided, it should point to a .kcl file or a directory containing a main.kcl file.

Sketches are grouped by constraint status: fully_constrained, under_constrained, over_constrained, and errors. Each sketch entry includes the sketch name, status, free_count (under-constrained segments), conflict_count (over-constrained segments), and total_count (total segments analyzed).

The report also includes kcl_executes_successfully (False when KCL parsing/execution failed before all sketches were analyzed) and kcl_error (None on success, otherwise a dict with phase ("parse" or "execution") and text fields describing the failure). A partial report may still contain sketch entries analyzed prior to the failure.

Args: kcl_code (str | None): The KCL code to check constraints for. kcl_path (str | None): The path to a KCL file or directory containing a main.kcl file.

Returns: dict | str: A report grouping sketches by constraint status, or an error message if the operation fails.

Replace the currently highlighted entities. Does NOT modify the "selection set".

This is a visual command: follow it with the snapshot tool, passing the same session_id and zoom=False, to see the highlight without moving the camera. It highlights edges, surfaces and bodies.

Highlighting only brightens an entity slightly. select_entities is markedly more obvious, tinting the entity and drawing an outline around it. For the strongest emphasis on a face, call both; on an edge call only one, because selection overrides the highlight. An edge is a pixel or two wide whichever you choose, so also consider center_camera_on_selection or a larger max_image_dimension to make one legible.

Highlights draw through the solid, so an entity facing away from the camera still renders, seen through the body. A highlighted entity in a snapshot is therefore not evidence that it faces the camera; choose a camera on the same side as the entity to see it properly.

Args: entity_ids: Entity UUIDs to highlight; pass an empty list to clear highlights. session_id: An open modeling session, from start_modeling_session. Required: highlights are scene state and would be discarded without one.

Returns: HighlightSetEntities: Confirmation that the highlights were replaced.

Import a CAD file into an existing modeling session.

Args: session_id: The ID returned by start_modeling_session. input_file: Path to a .fbx, .gltf, .obj, .ply, .sldprt, .step, .stp, or .stl file.

Returns: str: The modeling engine ID of the imported object.

Lint and fix KCL code given a string of KCL code or a path to a KCL project. Either kcl_code or kcl_path must be provided. If kcl_path is provided, it should point to a .kcl file or a directory containing .kcl files.

Args: kcl_code (str | None): The KCL code to lint and fix. kcl_path (str | None): The path to a KCL file to lint and fix. The path should point to a .kcl file or a directory containing a main.kcl file.

Returns: tuple[str, list[str]]: If kcl_code is provided, it returns a tuple containing the fixed KCL code and a list of unfixed lints. If kcl_path is provided, it returns a tuple containing a success message and a list of unfixed lints for each file in the project.

List all available KCL documentation topics organized by category.

Returns a dictionary with the following categories:

• kcl-lang: KCL language documentation (syntax, types, functions, etc.)

• kcl-std-functions: Standard library function documentation

• kcl-std-types: Standard library type documentation

• kcl-std-consts: Standard library constants documentation

• kcl-std-modules: Standard library module documentation

Each category contains a list of documentation file paths that can be retrieved using get_kcl_doc().

Returns: dict: Categories mapped to lists of available documentation paths.

Raises: ToolError: Documentation could not be fetched; the call can be retried.

List all available KCL sample projects.

Returns the public Aquarium projects from the Zoo API. Each sample demonstrates a CAD modeling technique or creates a particular 3D model.

Returns: list[dict]: List of sample information, each containing: - name: The public project ID (use with get_kcl_sample) - title: Human-readable title - description: Brief description of what the sample creates - multipleFiles: Whether the sample contains multiple KCL files. Best-effort hint only. The public listing doesn't expose file counts, so this is False for any sample that has not yet been fetched via get_kcl_sample. Call get_kcl_sample if you need a reliable answer.

Raises: ToolError: The sample index could not be fetched; the call can be retried.

List the datasets available to the user's organization.

Only datasets the organization has enabled for lookup are listed; datasets excluded from lookup (for example while their conversions are still being worked on) are omitted and should not be searched.

Each dataset has a UUID id, a human-readable name, and an optional description. Use the id as the dataset_id argument to search_org_dataset_semantic.

Returns: A list of {"id": str, "name": str, "description": str | None} entries, or an error message if the operation fails.

List the skills available to the user's organization.

Each skill has a UUID id, a human-readable name, a description, and a markdown body containing the skill's full content.

Returns: A list of {"id": str, "name": str, "description": str, "markdown": str} entries, or an error message if the operation fails.

Look up compact KCL reference sections. Prefer this for initial docs lookup.

Matches symbols, titles, headings, and keywords. Returns source paths and nonempty sections with complete examples and table rows when they fit. max_chars is a shared budget for Markdown content across all results (metadata is additional). Tables may omit rows within this budget. Truncated results can be expanded with get_kcl_doc(path). Both limits must be positive.

Mock execute KCL code given a string of KCL code or a path to a KCL project. Either kcl_code or kcl_path must be provided. If kcl_path is provided, it should point to a .kcl file or a directory containing a main.kcl file.

Args: kcl_code (str | None): The KCL code to mock execute. kcl_path (str | None): The path to a KCL file to mock execute. The path should point to a .kcl file or a directory containing a main.kcl file.

Returns: tuple(bool, str): Returns True if the KCL code executed successfully and a success message, False otherwise and the error message.

Search KCL samples by keyword.

Searches across all KCL sample titles and descriptions for the given query. Returns matching samples ranked by relevance.

Args: query (str): The search query (case-insensitive). max_results (int): Maximum number of results to return (default: 5).

Returns: list[dict]: List of search results, each containing: - name: The public project ID (use with get_kcl_sample) - title: Human-readable title - description: Brief description of the sample - multipleFiles: Whether the sample contains multiple KCL files. Best-effort hint only — see list_kcl_samples for the full caveat. Call get_kcl_sample if you need a reliable answer. - match_count: Number of times the query appears in title/description - excerpt: A relevant excerpt with the match in context

Raises: ToolError: The sample index could not be fetched; the call can be retried.

Semantic-search a dataset for samples relevant to the query.

Embeds the query with the org-dataset embedding model and returns the top chunk matches ranked by cosine similarity.

Args: dataset_id (str): The UUID of the dataset to search (from list_org_datasets). query (str): The natural-language query to embed and search with. limit (int | None): Optional max number of matches to return.

Returns: A list of match dicts (source_file_path, content, similarity, chunk_index, conversion_id), or an error message if the operation fails.

Replace the "selection set" with the given entities.

Takes UUIDs exactly as they appear in an artifact graph, and works for faces, edges, and solids alike.

Selected entities render with a distinct color tint and an outline, which is considerably more obvious in a snapshot than the subtler brightening that highlight_set_entities applies. For the strongest emphasis on a face, call both this and highlight_set_entities; for an edge use just one, as selection overrides the highlight. Follow with snapshot (passing zoom=False to keep the current camera) to see the result.

Selections draw through the solid. An entity facing away from the camera still renders tinted, seen through the body, so a tinted entity in a snapshot is not evidence that it faces the camera: an occluded edge shows up as an interior diagonal rather than on the silhouette, and an occluded face looks washed out rather than solid. Pick a camera on the same side as the entity to see it properly.

Args: entity_ids: Entity UUIDs to select; pass an empty list to clear the selection. session_id: An open modeling session, from start_modeling_session. Required: the selection is scene state and would be discarded without one.

Returns: SelectReplace: Confirmation that the selection was replaced.

Set which model entity types can be added to the "selection set".

Args: entity_types: Entity types permitted by the selection filter. session_id: An open modeling session, from start_modeling_session. Required: the filter is scene state and would be discarded without one.

Returns: SetSelectionFilter: Confirmation that the filter was set.

Render an open modeling session as an image.

Populate the scene first by passing this session_id to execute_kcl. The camera always uses an orthographic projection, so measurements read off the image are not distorted by perspective.

Args: session_id: A modeling session populated by execute_kcl. camera_view: Which view or views to capture. Omit it for a single isometric view. Otherwise one of:

    1. A named view: 'front', 'back', 'left', 'right', 'top',
       'bottom', 'isometric', 'isometric_front_right',
       'isometric_front_left', 'isometric_back_right',
       'isometric_back_left'.

       A named view puts the camera on that axis looking back at the
       origin, matching the app's standard views: 'front' is -Y,
       'back' is +Y, 'left' is -X, 'right' is +X, 'top' is +Z and
       'bottom' is -Z.

       So 'front' shows the face whose outward normal is -Y. The four
       isometric views all look down from above, from (+X, -Y, +Z)
       for 'isometric_front_right', (-X, -Y, +Z) for
       'isometric_front_left', (+X, +Y, +Z) for
       'isometric_back_right' and (-X, +Y, +Z) for
       'isometric_back_left'. Plain 'isometric' is front-right.

    2. A dict with "up", "vantage" and "center" keys, each a list of 3
       floats in model space: "vantage" is the camera position and
       "center" the point it looks at. For example
       {"up": [0, 0, 1], "vantage": [0, -1, 0], "center": [0, 0, 0]}
       looks at the origin from the front, showing the -Y face.

       With zoom=True only the direction from "center" to "vantage"
       matters, because zooming to fit sets the distance: [0, -1, 0]
       and [0, -200, 0] frame identically. "up" must not be parallel
       to that direction.

    3. 'multiview' for a 2x2 collage of front (top left), right (top
       right), top (bottom left) and isometric (bottom right).

    4. 'multi_isometric' for a 2x2 collage of the front-right (top
       left), front-left (top right), back-right (bottom left) and
       back-left (bottom right) isometric views.

    5. A list of up to 4 names and/or dicts, tiled in the order given.

zoom: Zoom to fit before capturing each view. Leave True unless you
      have positioned the session's camera yourself; a freshly
      executed scene is not framed, so zoom=False renders the model
      only a few pixels wide.
highlight_edges: Whether rendered edges should be outlined. Default is
                 False so that entities highlighted with
                 highlight_set_entities are obvious in the image.
max_image_dimension: Maximum width or height of the returned JPEG.
padding: Fraction of the frame left as margin when zooming to fit.
output_path: If provided, the snapshot is written to disk and the
             absolute file path is returned instead of the image. May
             be a file path (e.g. '/path/to/image.jpg') or a directory
             (in which case the file is named 'image.jpg'). If
             omitted, the image is returned inline as an ImageContent.
             The file is always JPEG data whatever extension is given,
             so prefer '.jpg' to avoid writing a JPEG named '.png'.

Returns: ImageContent | str: The snapshot as an inline image when output_path is omitted; otherwise the absolute path to the saved file.

Open an empty CPU modeling session for subsequent tools.

Only one modeling session can be open at a time. Stop the current session before starting another. If one is already open, or is still connecting, this fails with an error naming that session's ID so it can be stopped.

The server does not expire sessions after an idle or lifetime timeout. Callers are responsible for tracking and enforcing their desired timeout.

Pass the returned session_id to execute_kcl to populate the scene, then reuse it with modeling query, selection, and highlight tools. Stop the session explicitly with stop_modeling_session when finished.

Returns: str: The session ID to pass to session-aware modeling tools.

Close a persistent modeling websocket session.

Also accepts the ID of a session that is still connecting, which cancels that start and frees the slot for a new start_modeling_session call.

Args: session_id: The ID returned by start_modeling_session, or the one named by a "already open or starting" error.

Returns: None

Render a named 2D KCL sketch as a solver-debug PNG.

The image shows sketch geometry and solver freedom without requiring an existing modeling session. sketch_name is the sketch's variable name, such as profile in profile = sketch(on = XY) { ... }. Use get_sketch_constraint_status to discover sketch names when needed. A completed sketch may still be rendered after a later execution failure. A returned PNG does not mean the whole project executes successfully. If names repeat (for example, a function called twice), select an instance_index from a fresh constraint report for the same entrypoint.

Args: sketch_name: Variable name of the sketch to render. kcl_code: KCL source code containing the sketch. kcl_path: Path to a KCL file or project containing main.kcl. output_path: If provided, write the PNG to this file or directory and return its absolute path. A directory receives image.png. If omitted, return the PNG inline as ImageContent. instance_index: Zero-based creation order among sketches with this name. Omit for a unique name; refresh the report after edits.

Returns: The inline PNG, its saved absolute path, or an error message.