SolidMind CAD is an MCP bridge server that lets an LLM drive FreeCAD while keeping core engineering checks deterministic.
Primary runtime entrypoint: server/main.py
Primary runtime domains:
- Live CAD operations (
cad.*) - Manufacturing checks (
mfg.*) - Deterministic spec flow (
spec.*) - Deterministic ME preflight (
me.*) - Knowledge extraction/search (
knowledge.*) - Parametric geometry generators (
geometry.*) - Parametric design studies (
study.*) - Motion validation pipeline (
motion.*)
MCP Host (LLM app)
-> stdio JSON-RPC
server/main.py
-> TCP 127.0.0.1:9876
freecad_addon/socket_server.py (inside FreeCAD GUI)
This is the primary two-process architecture for live CAD work.
study.runstarts a background subprocess:python -m server.study_runner <study_id>.motion.simulatecan connect to optional Chrono daemon (127.0.0.1:9877), Isaac bridge (127.0.0.1:9878), or Gazebo bridge (127.0.0.1:9879).
If sidecars are absent, base CAD/ME/spec workflows remain available.
server/main.py supports both:
- LSP/MCP framing (
Content-Lengthheaders) - newline-delimited JSON fallback (for manual/debug use)
Reference implementation path: server/main.py message reader (_read_message).
Socket protocol is newline-delimited JSON:
- Request:
{"cmd":"pad","args":{...}} - Response:
{"ok":true,"result":{...}}or{"ok":false,"error":"..."}
Client: server/freecad_client.py
Server: freecad_addon/socket_server.py
TCP newline-delimited JSON client in server/chrono_client.py.
Default endpoint: 127.0.0.1:9877.
| Family | Count | Module |
|---|---|---|
cad.* |
33 | server/tools_cad.py |
mfg.* |
3 | server/tools_mfg.py |
spec.* |
10 | server/tools.py |
me.* |
5 | server/tools_me.py |
knowledge.* |
5 | server/tools_knowledge.py |
geometry.* |
5 | server/tools_geometry.py |
study.* |
7 | server/tools_study.py |
motion.* |
13 | server/tools_motion.py |
cad.new_document, cad.new_body, cad.sketch, cad.pad, cad.revolution, cad.polar_pattern, cad.pocket, cad.sweep, cad.helix, cad.loft, cad.hole, cad.fillet, cad.chamfer, cad.get_selection, cad.get_model_tree, cad.get_dimensions, cad.get_body_topology, cad.find_edges, cad.define_selection, cad.resolve_selection, cad.list_selections, cad.delete_selection, cad.screenshot, cad.set_camera, cad.get_camera, cad.undo, cad.export, cad.delete_objects, cad.set_placement, cad.set_visibility, cad.animate, cad.animate_stop, cad.freecad_info.
mfg.set_property, mfg.readiness_check, mfg.export_rfq.
spec.select_schema, spec.apply_answer, spec.validate, spec.next_question, spec.finalize, spec.export_brief, spec.export_rfq_summary, spec.assess_design_path, spec.generate_cad, spec.plan_geometry.
me.validate_constraints, me.build_traceability, me.apply_risk_gates, me.design_loop, me.list_validators.
knowledge.extract, knowledge.ingest, knowledge.ingest_status, knowledge.search, knowledge.status.
geometry.spur_gear, geometry.tooth_slot, geometry.gear_params, geometry.planetary_layout, geometry.involute_points.
study.create, study.run, study.status, study.results, study.cancel, study.list, study.get_variant.
motion.define_mechanism, motion.list_mechanisms, motion.validate, motion.propagate_motion, motion.check_gear_train, motion.create_assembly, motion.drive_joint, motion.check_interference, motion.simulate, motion.teleop_start, motion.teleop_command, motion.teleop_state, motion.teleop_stop.
cad_copilot_systemknowledge_research_workflow
Command registry in freecad_addon/commands.py includes:
- Document:
new_document,new_body,get_model_tree,undo,redo - Sketcher:
new_sketch,sketch_rect,sketch_circle,sketch_line,sketch_arc,sketch_bspline,sketch_constrain,sketch_populate,close_sketch - PartDesign and helpers:
pad,resolve_pocket_direction,pocket,revolution,polar_pattern,hole,sweep,helix,loft,fillet,chamfer - Query and selection:
get_selection,get_dimensions,get_body_topology,find_edges,define_selection,resolve_selection,list_selections,delete_selection - Visualization/visibility:
screenshot,set_camera,get_camera,set_visibility - Export:
export,export_body - Assembly:
assembly_create,assembly_add_part,assembly_add_joint,assembly_solve,assembly_drive_joint,assembly_check_interference,assembly_get_placements
Implementation modules:
- Models:
server/motion_models.py - Store:
server/motion_store.py - Validators:
server/motion_validators.py - MCP wrapper tools:
server/tools_motion.py - Optional dynamic clients:
server/chrono_client.py,server/isaac_client.py - Isaac sidecar runtime:
isaac_bridge/bridge_server.py,isaac_bridge/runtime_isaac.py,isaac_bridge/protocol.py
Tiered behavior:
- Tier 0 mechanism definition
motion.define_mechanismvalidates shape, stores mechanism, returnsmechanism_id.
- Tier 1 analytical checks (no FreeCAD/Chrono required)
- Ratio consistency, speed/torque propagation, power, DOF, planetary/linkage heuristics, expected-output matching.
- Tier 2 kinematic FreeCAD Assembly checks
- Builds assembly links/joints, solves constraints, drives joints, checks interference.
- Tier 3 dynamic simulation via selected backend
motion.simulatesupportsbackend=chrono|isaac|gazebo(defaultisaac).motion.simulatesupportsmode=batch|teleop(teleop for Isaac and Gazebo; Chrono is batch-only).motion.simulateaccepts optionalprofilefor Isaac runtime overrides.- For Gazebo backend,
urdf_pathorsdf_pathis required (SDF preferred for drone workflows). - If requested backend is absent, returns deterministic
BACKEND_UNAVAILABLE_CHOOSEwith explicit retry choices (no implicit fallback). - Teleop lifecycle is exposed via
motion.teleop_start,motion.teleop_command,motion.teleop_state,motion.teleop_stop. - Gazebo teleop controller contract:
profile.controller_type in {multirotor_direct, px4_offboard}. - Isaac bridge v1 supported joints:
revolute,prismatic,fixed. - Isaac bridge v1 returns deterministic
UNSUPPORTED_JOINT_TYPEforgear_mesh,belt_chain,cam,planar.
Core modules:
- API wrappers:
server/tools_study.py - Models:
server/study_models.py - Persistence:
server/study_store.py - Runner:
server/study_runner.py - Solvers:
server/study_solvers.py
Execution model:
study.create
- Validates variables/objective/solver.
- Stores study under
studies/<study_id>/study.json. - Returns coarse/refined variant count estimates and ETA.
study.run
- Spawns
server.study_runnersubprocess.
study_runner
- Executes coarse cartesian sweep.
- Refines near best coarse point.
- Ranks feasible variants and sets
best_variant_id.
study.status/study.results
- Poll progress, ETA, and ranked outputs.
Solver registry currently includes:
mock: deterministic test solver.bemt_xfoil: scaffolded (not yet implemented).openfoam: partial pipeline (geometry stage implemented; solve stage currently stubbed).chrono: dynamic metrics via Chrono daemon.
The tranche-1 spine of docs/target-architecture.md: content-addressed
artifacts, pure functions between them. A study created with driver set
routes through this path instead of the legacy solver loop; the public
study.* surface is unchanged.
Documents (all hashed sha256(jcs.canonicalize(doc)), no float rounding —
unlike compute_gir_hash's precision-10 normalization, because the analytic
tier's audit standard is bit-exact):
dg.structure/v1— components, interfaces, frames, materials, and aParamSpec(path/unit/kind/validity-domain/provenance) for every bindable leaf. Shape, never values.dg.params/v1— values at stable RFC 6901 paths; leaves are{"value", "unit"}objects and bindings replace onlyvalue.dg.revision/v1—{structure_hash, params_hash, parent}; the revision id is the manifest's content hash.eval.request/v1/eval.result/v1— the evaluator contract. The request hash (cache key) includes environment identity and per-stage model identities; result bodies carry no timestamps (timing lives in variants and job records).eval.materialized/v1— every requested stage's derived inputs; its hash is the output fingerprint used by the layered binding check.
Modules:
- CAS:
server/artifact_store.py(artifacts/objects|refs|lineage, atomic tmp+rename, self-verifying reads),server/env_identity.py. - Design graph:
server/dg_models.py,server/dg_store.py,server/dg_import.py(brief importer; revision zero),server/dg_binding.py(layer 1 = unknown/undeclared/type-mismatch binding → hard fail before materialization; layer 2 = applied binding with unchanged materialized fingerprint →flags.unchanged_fingerprint, a zero-sensitivity signal). - Evaluator CLI:
python -m server.evaluator <request> <result>; exit codes 0 ok (incl. cache replay), 1 internal, 2 binding hard-fail, 3 invalid request/revision, 4 model error. Stages (server/eval_stages.py) are identified models (analytic_latch/v1) in tiers (analytic now; field/world reserved). - Driver seam:
server/study_drivers.py(StudyDriverABC,GridDriverreusing the legacy grid builders,DakotaDrivergated on the binary),server/dakota_io.py(params.in/results.out codecs + thepython -m server.dakota_io forkanalysis-driver bridge, proven against a fake Dakota double). - Durable jobs:
server/jobs.py(PID +/procstart-ticks identity, enforced transitions, cancel flag file,recover_stale),server/study_driver_runner.py(evaluator subprocesses, SIGTERM→wait→SIGKILL cancellation that reaches in-flight children). Restart recovery is re-run + cache replay: completed evaluations are cache hits, so a crashed sweep resumes at ~zero cost.
MCP surface: dgraph.import_brief / dgraph.get_revision /
dgraph.list_revisions, plus optional driver/revision/scenario/models
on study.create (with per-variable binding path and the evaluator
solver sentinel).
Machinery that tests the architecture's central claim — that an LLM earns its place by compiling open-world engineering knowledge into executable, validity-checked model edits — and can falsify it.
Model registry (server/model_registry.py). Stages are built from named
terms; a model-chain artifact (dg.models/v1) says which are enabled. A
chain with a term ablated changes that stage's identity, which is part of
the evaluation cache key, so an ablated run can never replay a full model's
result. Terms carry calibrated; uncalibrated ones (literature
parameterizations) are reported on every result they touch.
Second domain (server/acoustics.py, analytic_acoustic_bearing stage,
server/dg_acoustic.py). Knapp–Carter TDOA variance, Kolmogorov 5/3
turbulence coherence, a Ziv–Zakai-style threshold/ambiguity blend (the CRLB is
a local bound — bound-only models are optimistic exactly at the coverage
boundary), and bearings-only GDOP fusion. Node placements live in the design
graph, because placement is the design variable of a detection mesh.
Diagnosis (server/diagnose.py). diagnose(results, study) — a
deterministic checklist: optimum at a bound, flat objective, no-op bindings
(a cluster of unchanged fingerprints, never a single one), validity-domain
hits, infeasibility, mass evaluation failure. It runs before any LLM and is
the baseline the LLM arm has to beat.
Prescription (server/prescribe.py). Four legal action forms — patch,
request_measurement, escalate, no_action — with Addendum A.1 gates:
design graph and study variables/bounds free; model registry
calibration-gated; study objectives/constraints and scenario
human-approval-gated. apply_action executes patches into new artifact
revisions; gated patches without approval are refused, never dropped.
Benchmark (server/benchmark.py). Problems across both domains covering
four defect classes plus no-defect controls, scored against the Addendum A.2
answer key. The missing mechanism class is seeded by ablating a term
from a working chain (so the restoring patch executes immediately) and the
ablated term is withheld from the catalog arms can see, keeping it an
open-vocabulary proposal rather than a menu lookup. Scoring separates the
controls row so the false-alarm rate — the number the gate turns on — is
visible. The checklist baseline is recorded, not assumed:
hit rate 0.25, false-alarm rate 0.00
It catches the parameterization defect and is blind to topology, wrong objectives, and missing mechanisms — on the ablated-physics problem it recommends widening the bound, pushing further into the model's blind spot. That asymmetry is what the LLM arm has to beat.
Modules:
- Tool layer:
server/tools_knowledge.py - Store:
server/knowledge_store.py
Modes:
- Extract: parse a file and return text (
knowledge.extract). - Ingest: synchronous extract/chunk/embed/store (
knowledge.ingest). - Search: semantic/hybrid search (
knowledge.search). - Status: store/index health (
knowledge.status).
Fallback behavior:
- If store dependencies are unavailable, tools degrade to local
me_knowledge/noteslisting where applicable.
spec.apply_answer uses JSON pointer paths with operations:
setappendremove
This is intentionally smaller and more LLM-robust than full RFC6902 patch arrays.
geometry.* tools return geometry_ref handles; raw element arrays stay server-side in server/geometry_store.py.
cad.sketch resolves these handles server-side before calling FreeCAD.
cad.sketch is a compound call:
new_sketch- single batched
sketch_populate close_sketch
This avoids per-element RPC chatter and recompute storms.
Feature operations return structured data used by the LLM for grounded reasoning:
face_mapoperation_summary- digest/delta metadata
- verification images
selection_driftstatus for named selectors
Spec-driven geometry path:
spec -> GIR -> strategy/planning policy -> EIR -> compiler/executor -> CAD operations
Primary modules:
server/geometry_ir.pyserver/geometry_planning.pyserver/geometry_planner.pyserver/geometry_compiler_freecad.pyserver/geometry_executor.pyserver/geometry_constraints.pyserver/geometry_references.pyserver/geometry_verify.py
Policy/capability files:
feature_support/geometry_capabilities.ymlfeature_support/verification_policy.ymlfeature_support/planning_policy.yml
- Stable sorting and deterministic thresholds in ME/motion validators.
- Deterministic spec finalization and hashing via canonicalization (
server/jcs.py). - Session-scoped deterministic handle stores (
geometry_store,motion_store). - Explicit error codes for dependency absence (FreeCAD connection errors, Chrono availability errors, tool-level structured errors).
- Unit-test coverage across tool surfaces, models, stores, and runners.
server/main.py
|
---------------------------------------------------------------
| | | | | | | |
cad.* mfg.* spec.* me.* knowledge.* geometry.* study.* motion.*
| | | |
freecad_client.py geometry_store study_runner chrono_client
|
freecad_addon (socket_server + commands)
server/main.py: MCP server, tool schemas, dispatch, framing supportserver/tools_cad.py: CAD MCP wrappersserver/tools.py: spec toolsserver/tools_me.py: ME deterministic loop wrappersserver/tools_knowledge.py: knowledge workflowsserver/tools_geometry.py: geometry generatorsserver/tools_study.py: study API wrappersserver/tools_motion.py: motion tool wrappersserver/study_runner.py: background study execution engineserver/study_solvers.py: solver adapters/registryserver/chrono_client.py: optional Chrono TCP clientfreecad_addon/commands.py: FreeCAD-side command handlersfreecad_addon/socket_server.py: FreeCAD-side TCP server
- Keep the core CAD path simple and always available (two-process bridge).
- Add specialized simulation capabilities as opt-in sidecars (study runner, Chrono).
- Keep high-value engineering logic deterministic while using LLMs for intent translation and orchestration.
- Use handle-based dataflow and structured operation feedback to reduce LLM token load and ambiguity.