build123d-mcp: Instructions file for Claude Code

build123d-mcp

Running tests

Always use uv run pytest — it auto-installs all dependencies from pyproject.toml before running.

uv run pytest tests/

The target is 100% passing. There are no accepted pre-existing failures — if tests are failing, fix them.

Running the server

uv tool run --python 3.12 build123d-mcp

Communicates over stdio (MCP SDK v2 MCPServer). When configuring an MCP client, set cwd to the project root.

Project structure

server.py          — MCPServer entry point; registers all MCP tools; holds module-level _session singleton
session.py         — Persistent state: namespace, current_shape, objects dict, snapshots
security.py        — Three-layer defence: AST check → restricted builtins → exec timeout
session_registry.py — Per-handle CAD sessions for HTTP (cap + idle eviction)
tools/execute.py   — Thin wrapper delegating to session.execute()
tools/render.py    — pyvista-based PNG rendering; headless (xvfb) if no DISPLAY
tools/measure.py   — Geometry queries returning JSON (bounding_box, volume, area, wall thickness, clearance)
tools/export.py    — STEP/STL export; path traversal blocked

Adding a new tool

1. Create tools/<name>.py with a function def <name>(session, ...) -> str. Optional parameters must carry their defaults on this function — the worker wire omits arguments the caller didn't supply.
2. Add a typed stub method on WorkerSession in worker.py:

   @_op(_tool(f"{_T}.<name>:<name>"), _GEOMETRY_TIMEOUT)
   def <name>(self, arg1: str, arg2: float = 0.0) -> str:
       raise NotImplementedError
   

   The @_op decorator registers the op in _OPS and replaces the body with bind-and-send — the signature is the single typed wire interface, so keep its defaults equal to the tool function's. Ops that need more than fn(session, **args) in the worker get a small _op_<name> handler instead of _tool(...).
3. Register in server.py:

   @mcp.tool()
   def <name>(...) -> str:
       """Docstring shown to MCP clients."""
       return _session.<name>(...)
   

4. Classify the op in tests/test_worker_boundary_coverage.py (add it to the smoke inventory, SESSION_STATEFUL_TOOLS, or the reasoned allowlist) — test_every_dispatch_op_is_classified fails until you do.