---
name: freecad-engineering-bootstrap
description: Set up, diagnose, or migrate a portable FreeCAD plus MCP environment for AI-assisted CAD on Linux, macOS, or Windows. Use when an agent needs to discover an existing FreeCAD/MCP installation, compare upstream package versus source-build options, install an MCP bridge with informed user approval, register it with an agent host, or troubleshoot the resulting connection without assuming Codex, Claude, or any single vendor.
license: MIT
metadata:
  dev.v-san.skills: |-
    origin: original (personal skill)
    version: '0.1'
    changeDate: '2026-08-12'
    authors:
      - Vladimir Rogozhin
    requires:
      dependencies:
        - FreeCAD 1.0+ (FreeCAD 1.1+ recommended)
        - Python 3.11+
    sources:
      - https://github.com/neka-nat/freecad-mcp
      - https://github.com/contextform/freecad-mcp
      - https://github.com/spkane/freecad-addon-robust-mcp-server
      - https://github.com/ghbalf/freecad-ai
---

# FreeCAD Engineering Bootstrap

Build a reproducible FreeCAD engineering environment while leaving installation and trust choices with the user. Treat the Agent Skill as the portable control plane; treat FreeCAD, an MCP bridge, and the host configuration as replaceable dependencies.

## Workflow

1. Run `python scripts/bootstrap_probe.py` before proposing changes. Use `--json` when another script will consume the result.
2. Read [provider-matrix.md](references/provider-matrix.md) and identify one bridge whose capabilities match the task. Do not run two bridges against one FreeCAD session merely to increase tool count.
3. Read [solver-backends.md](references/solver-backends.md) when the task includes FEM. Require CalculiX and a supported mesher for the linear-static baseline. Treat Elmer as optional unless a named multiphysics equation requires it.
4. Present these installation choices when applicable:
   - use an existing command or installation;
   - run the upstream package or launcher;
   - install from source at a release, branch, or exact commit.
5. Explain the practical trust and update trade-off in one short paragraph. Recommend a sensible option, but do not make pinning or source builds mandatory.
6. Show the exact commands and target paths before changing the machine. Ask for approval before installing software, copying an add-on, writing a host config, or starting a service.
7. Discover FreeCAD's actual user-data directory rather than assuming a Linux path. Prefer FreeCAD's `UserAppData` configuration value when a runnable `FreeCADCmd` is available.
8. Register the bridge as a normal local process using the host's documented MCP mechanism. Use `scripts/render_mcp_config.py` to render generic JSON, TOML, or a Codex CLI command; the skill workflow itself must remain host-neutral.
9. Start FreeCAD and its add-on, then perform the read-only capability checks in [capability-contract.md](references/capability-contract.md). Run a mutation smoke test only in a new scratch document.
10. Report the chosen provider, installation method, source/ref if any, add-on path, launch command, host config location, solver capabilities, and smoke-test result. Record unknowns explicitly.

## Safety and recovery

Read [security-and-recovery.md](references/security-and-recovery.md) before executing install commands or arbitrary FreeCAD Python.

- Prefer narrow MCP tools for ordinary document operations. Treat arbitrary Python execution as a powerful fallback, not a setup failure.
- Keep local bridges loopback-only by default. If remote access is requested, stop and design authentication and network boundaries explicitly.
- Never paste secrets into skill files or generated configuration examples.
- Preserve the user's working FreeCAD document. Use a new scratch document for setup validation and close it without saving unless the user asks to keep it.
- Make rollback concrete: preserve the previous config, identify copied add-on files, and state how to remove or disable them.

## Platform handling

- On Linux, account for native packages, AppImage, and Flatpak. A Flatpak user-data directory differs from a native install.
- On macOS, check `/Applications/FreeCAD.app` and user Library locations, but verify them from the installed application before writing.
- On Windows, discover executables and `%APPDATA%`/FreeCAD paths rather than translating Unix commands literally.
- Label a platform path as unverified when it came from documentation but was not exercised on the current machine.

## Resources

- `scripts/bootstrap_probe.py` — read-only host and installation inventory.
- `scripts/render_mcp_config.py` — deterministic configuration renderer; writes only when `--output` is supplied.
- [provider-matrix.md](references/provider-matrix.md) — provider and installation-method selection.
- [solver-backends.md](references/solver-backends.md) — CalculiX/Gmsh baseline, optional Elmer, and Flatpak boundaries.
- [capability-contract.md](references/capability-contract.md) — provider-neutral acceptance checks.
- [security-and-recovery.md](references/security-and-recovery.md) — advisory risk and rollback guidance.
- [provenance.md](references/provenance.md) — upstream ideas and the audited snapshot.