ClassCAD

The signed-in classcad.ch account: its plan (and until when), whether it allows commercial use, which exports, and WHERE A WEB APP built with ClassCAD may run under it — localhost always (any port), public https domains only as registered on the account (from the plan that has them) — plus the public access token (ccpk_…) that goes into the app's page, or where to make one. Call it FIRST when the user wants their own app, website, configurator or deployment around a model; then follow docs(["recipes/buerli-app"]). Read-only: tokens and domains are made on the account page.

Save the WHOLE drawing state under a label (in-memory, server-side — cheap and instant). Use BEFORE risky sequences (large booleans, trims, experiments): if the attempt goes wrong, restore({label}) brings the drawing back exactly instead of delete-archaeology. Re-using a label overwrites it; at most 5 checkpoints are kept (oldest dropped). Checkpoints die with the server process and with a use_session switch.

Empty the drawing (v1.common.clear), to start over in it: a drawing persists between requests, part.create refuses a second root, and anything built on the old part would carry its geometry along. For a new, unrelated model next to this one, open a new drawing instead (drawing: "new"). Not needed for changes to the current model. The graphic and renders are empty afterwards too — no reconnect needed.

Full documentation for ONE key — prefer docs([...]) to fetch everything you need in a single round; use this only for a single follow-up lookup. Accepts full ("v1.part.box") or bare ("box") names — ambiguous bare names list the candidates. Also serves whole documents ("DATA", "api/part", "recipes/parametric-part"). Same size cap and paging as docs: a large document answers with page 1 and names the next page ("api/part#2").

Fetch documentation in BULK — one call, many documents. Keys can be: v1 methods ("v1.part.box" or a unique bare name), topic docs ("DATA", "STRUCTURE", "GRAPHICS"), recipes ("recipes/verification" — MANDATORY in every build fetch, "recipes/clean-construction" — every assembly and multi-part model, "recipes/constrained-sketching", "recipes/parametric-part", "recipes/assembly-parameters", "recipes/pattern-then-subtract", "recipes/direct-modeling-eif", "recipes/buerli-app"), guides ("part/expression-workflow", "assembly/generic", …) and domain overviews ("api/part"). PLAN FIRST: pick every method you will need from the method index, then request them plus the matching recipe/guide docs in ONE call (up to 24 keys), recipes first. Each response is capped at ~48k chars: docs that don't fit are listed at the TOP as "NOT included yet" — request exactly those keys in a follow-up call before building. Docs larger than one response are paged: "key" is page 1, "key#2" the next (the page footer says so). Unknown keys come back in a "not found" section with suggestions. Find recipes/guides by topic with the method search (list_methods), which also returns matching documents.

Search the cached structure tree by class and/or name substring. Returns slim records (id, class, name, parent).

What the user has selected in the app docked into this session: faces, edges and vertices of a body, or objects of the model tree (sketch entities, dimensions, features). Call it when the user points at something instead of naming it ("this face", "the selected edges", "here"). Each item has `kind` (face | edge | vertex | object) and `objectId` — the tree object: the picked object itself, or the solid a picked face, edge or vertex belongs to (`object` names its class). Geometry also has `graphicId`, the id API calls take for that face, edge or vertex (e.g. v1.sketch.create({ planeId })), its `type` (plane, cylinder, line, arc, …), `containerId` and `prodRefId`. A selection keeps the ids it was made with: after a feature rebuilds the body, its `containerId` and `objectId` name the old, consumed body (faces and edges the feature did not touch keep their `graphicId`; a recalc renumbers them all). Read the selection right before you use it.

Return the full record for a single tree node by ID, including members and children.

Search/list the v1.<domain>.<method> surface. `search` as a string: one BM25-ranked list over method name + summary (whole words), CAD synonyms expanded (split→slice, hole→bore, round→fillet, …). `search` as an ARRAY with ONE CONCEPT PER ENTRY (e.g. ["expression", "box", "fastened constraint", "mass properties"]): one group per entry, each ranked on its own, so every concept gets its own top matches (a group note flags entries that are likely workflows, not methods). PLUS `docs`: the recipes/guides whose title, headings or text match (e.g. "shared parameters assembly" → recipes/assembly-parameters) — search by what you want to build, then fetch those docs. Without `search`: the full method listing plus `documents` (every recipe and guide, key — title). withSummaries=false returns bare names (token-cheap). A no-hit result does NOT mean the operation is missing — browse the domain instead.

Load a drawing, replacing the current one: from a file on disk (`path`) or from base64-encoded content. Formats: STP (STEP), STL, OFB, JSON. Prefer `path`: the file is read here and never passes through the conversation, which is the only practical way for a model file of real size. Give exactly one of `path` and `content`.

Sign this machine in to ClassCAD (a free classcad.ch account; Google, GitHub or email). Call it RIGHT AFTER installing the MCP. Not signed in: the first call opens the sign-in page in the user's browser and returns its link — show it to the user as a clickable link too — and the next call WAITS (up to ~50 s per call) until they have signed in in the browser, then returns their account. Call again while it reports "still waiting". Already signed in: returns the account at once. logout: true signs the machine out.

Replace the drawing with a previously checkpointed state (clear + reload). Without a label, the MOST RECENT checkpoint is restored. All ids from after the checkpoint are stale afterwards — re-read them (tree/find) before further operations.

Execute JavaScript against the CAD session — THE tool for any build involving computation, repetition, or more than a handful of operations. The script runs as an async function body with: • api.v1.<domain>.<method>(params) — ClassCAD calls, await-able, → { result, maxLevel, messages }. Typos throw immediately with suggestions. Strict: a call that ends at maxLevel ≥ 51 THROWS (the message carries the engine error) — method docs describing "null/[] with maxLevel 51" are the non-script result; wrap intentional probes (e.g. getGeometryIds where a miss is expected) in try/catch. • await api.tree({ refresh? }) — the structure tree (id → node): find parts, features, sketches by class/name. Returns a Promise: without await, Object.values(api.tree()) is silently [] (looks like an empty drawing). • await api.graphic({ recalc? }) — the graphic payload (containers with face meshes, edges, vertices): find and FILTER GEOMETRY yourself — e.g. locate a bore wall by vertex radius, collect edge ids for a chamfer. Exact shapes + selection idioms: docs(["DATA"]). • Math, full JS (variables, loops, functions); console.log/log(...) captured and returned. • return <small summary> — results are size-capped; keep big data in the drawing, not the return value. Compute coordinates IN the script (trigonometry, loops) instead of inlining hand-evaluated numbers. Pass recalc:false to api.graphic() in solid.*/entity-injection sessions (a recalc invalidates curve shape ids and can destroy injected bodies in complex cases). No DOM/network/filesystem access; awaited work times out (default 60s). Prefer several small verified scripts over one huge one — STATE PERSISTS in the drawing between scripts: a follow-up script ATTACHES to the existing model (re-discover via await api.tree(); tree ids are stable; NEVER part.create when a part already exists). Even a single operation is a run_script.

Write the current drawing to a file, or return it as base64. Formats: STP (STEP, exact geometry), STL (triangles), GLB (binary glTF: triangles with colours, for 3D viewers and the web), OFB (ClassCAD's own format: the model with its features, to open again in ClassCAD or Buerligons), JSON. With `path` the file is written to disk and only its path and size come back — the way to hand the user a model (give them the path); without it the content is returned base64-encoded, which is large. The user can also save the model themselves from what `view` opens.

Return ClassCAD MCP session status: the drawing's id, the link of the app docked into this session (app) or of the read-only 3D view (viewer), the link the session is shared with others under (shared; null while it is not), who else is in the session (peers), sign-in (auth), transport (ws = ClassCAD worker, wasm = the MCP's own local engine), engine policy, whether a local WASM engine is available, WS URL, current session id, the invite this session joined with (shareToken), connection state, package version. DAEMON: every connection of a host to this MCP is a session in ONE shared daemon process per machine (127.0.0.1:9097), with the drawings its conversations opened; it exits a minute after its last session. Rebuilt MCP/renderer code only runs in a new daemon — an idle one is replaced automatically. Shell commands: `node "/workdir/node_modules/@classcad/mcp/dist/server.js" status` (pid, build, sessions); `node "/workdir/node_modules/@classcad/mcp/dist/server.js" stop` (stops it only when no session is active); `node "/workdir/node_modules/@classcad/mcp/dist/server.js" stop --force` (terminates it NOW — every connected host, this one included, loses its drawings: ask the user first. Tabs reconnect to a fresh daemon on their next tool call; tabs started before this MCP version need a host restart). Never kill daemon processes by hand.

Selects things in the app docked into this session, so the user sees what you mean: faces, edges or vertices by their `graphicId` (from getGeometryIds, pick results or get_selection), tree objects by their `objectId`. The app highlights them. Returns what is selected there afterwards. Geometry ids must be current ones (see get_selection); pass `prodRefId` from a previous get_selection when the part is an instance in an assembly. An empty `items` clears the selection.

A link to this session's app that works from ANYWHERE: for another person, or for the user on another device (the link `view` returns works on this machine only). Whoever opens it is in this session like the user at the app — they see the model live as you build it, and can turn, select and edit it. Call it when the user asks to share, send or show the model to somebody, or to open it somewhere else. Not on your own: the link lets EVERYONE who has it into the session, so it is a secret between the user and whom they send it to — hand it to the user, as a clickable link on its own line, and put it nowhere else. The session stays on this machine; guests reach it through the ClassCAD share relay, which passes the data on and keeps none of it. The link works until the session ends or sharing is stopped. When the share service cannot be reached, nothing fails: you are told so, the app keeps working on this machine, and the session is shared as soon as the service is back. stop: true takes it back: it stops working and whoever joined with it is disconnected. Sharing again afterwards gives a new link.

Render the current drawing as an inline PNG (also written to disk: outDir, else $CLASSCAD_SNAPSHOT_DIR, else <tmpdir>/classcad-snapshots). The image is returned to the MODEL as an inline image block — no follow-up Read is needed to see it. The USER usually does not see tool results. At the end of a build (not after every tweak), SHOW them the render: with a file-sending tool (Claude Code: SendUserFile), send the saved PNG; otherwise embed it in your reply as a Markdown image with its absolute path,  — Codex and most chat hosts display that. Hosts preview only files inside the session's own folders (Claude Code: the scratchpad directory or the project) — anywhere else the user gets a grey placeholder card. So when you intend to send the render, pass outDir = your scratchpad directory (or a folder in the project). Call after a meaningful geometry change, NOT after every parameter tweak. Verification options: section (cut through internals), sheet (four labeled views, shared ortho scale), drawing (technical drawing: front/top/side with hidden lines dashed, placed first- or third-angle — compare against a reference drawing), lines (line style: visible edges solid, hidden dashed), highlight (face/edge/body ids in signal color), markers (probe crosshairs at world points), sketchOverlay (sketch curves on their real plane), annotate (extents + axes triad + scale bar), xray (hidden geometry shines through), colors "distinct" (one color per body — booleans/splits/patterns), frame (pin an earlier snapshot's reported frame for pixel-comparable before/after).

Return the cached drawing structure tree. Pass refresh=true to force a fresh server fetch first.

Make this the FIRST call of a drawing (drawing: "new") when the user names a session or hands you a session/token URL — a drawing opens its engine link lazily, so its first tool call decides which session it is. Modes: (1) sessionId — attaches to a named ClassCAD session (ClassCAD-Session-Id header) on the configured worker; empty/omitted = fresh worker-assigned session. (2) url — a ws(s):// URL from a multi-client server, typically carrying an invite token (wss://host/?invite=…); connected VERBATIM. (3) an http(s):// APP SHARE LINK from a buerli app's Session Management (…?invite=…): the MCP joins the app's session as a guest, wherever its engine runs — on a ClassCAD server (the token is applied to the configured worker URL) or in the app's own page (WASM; the app must stay open: on this machine, or anywhere when it shares on the ClassCAD share relay, as buerligons.io does). Without a url the MCP runs its own session — and the user's app docks into THAT with the link `view` returns. (4) engine — WHICH ENGINE runs that own session: "drogon" = the configured ClassCAD worker (server), "wasm" = the MCP's OWN local engine (the published WASM build hosted in this process, no server and no browser needed; requires a configured key), "auto" (default) = the worker if reachable, otherwise the local engine. Use "drogon" when the user says to connect to their (Drogon/ClassCAD) server, "wasm" when they say WASM/local/offline; a token or URL always decides by itself. Reconnecting clears cached structure/graphic state — the next tool call repopulates it.

The live CAD app of this session (Buerligons), docked into the same engine: returns its link and says how to bring it up. Where the session is shared from the start the link is its share link (it works from anywhere); local: true returns the link that works on this machine only instead — for when the share link does not load. The app shows every change as it happens, and the user can work in it — turn and zoom, select, measure, edit sketches and features, export STEP or STL. Call it when the user asks to see, turn or edit the model, or asks for the link. If the user already has it open, nothing is opened. Otherwise it is opened in the user's default browser — or, when your host has a browser pane of its own, you are told to open the link there. open: false only returns the link; open: true opens the user's default browser whatever the host.