Zoo MCP

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 or exec_kcl_project. 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 or exec_kcl_project. 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 or exec_kcl_project. 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 or exec_kcl_project. Returns: EntityGetSketchPaths: The sketch path UUIDs belonging to the entity.

Mock preflight a KCL project, then run it in the session and save its artifact graph. Both stages use the same captured project. Mock errors return immediately without starting real execution. Mock warnings remain visible and allow it. Known mock-engine limitations are reported as warnings for real execution. Args: kcl_code (str | None): Self-contained KCL code to run as a single-file project. Standard-library imports are allowed; filesystem imports require kcl_path. kcl_path (str | None): A .kcl file or project directory containing main.kcl. Dependencies and symlink targets must rem…

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. 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 p…

Export KCL code to a CAD file. 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. This tool does not save editable KCL source. For model creation, include the saved KCL project alongside any requested CAD exports unless the user explicitly requests export-only output. Args: kcl_code (str | None): The KCL code to export to a CAD file. kcl_path (str | None): The path to a KCL file to export to a CAD file. The path should point to a .kcl file or a directory containing a main.kcl file. expor…

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 or exec_kcl_project. 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. Use list_kcl_docs() to see available documentation paths, or search_kcl_docs() to find relevant documentation by keyword. 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 de…

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 al…

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…

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 kc…

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 pa…

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 ``Fal…

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.

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.

Save an ImageContent object to disk. This allows a human to review images locally that an LLM has requested. Args: image (ImageContent): The ImageContent object to save. This is typically returned by the snapshot tool. Note that snapshot can write straight to disk via its own output_path argument; this tool is for images you already hold. output_path (str | None): The path where the image should be saved. Can be a file path (e.g., '/path/to/image.jpg') or a directory (e.g., '/path/to/dir'). If a directory is provided, the file will be named 'image.jpg'. If not provided, a temporary fi…

Search KCL documentation by keyword. Searches across all KCL language and standard library documentation for the given query. Returns relevant excerpts with surrounding context. 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: - path: The documentation file path - title: The document title (from first heading) - excerpt: A relevant excerpt with the match highlighted in context - match_count: Number of times the …

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-…

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 throu…

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 or exec_kcl_project. 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 or exec_kcl_project. 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', …

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 or exec_kcl_project to populate the scene, then reuse it with modeling query, selection, and highlight tools. Stop the session expli…

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 …