# fusion-spatial-mcp

An MCP server that gives AI agents **genuine 3D spatial understanding of
Autodesk Fusion 360** — exact measurements, collision/clearance/containment,
volumetric occupancy, section cuts, engineering multiviews, and free-space
placement search — plus **Fusion-native parametric authoring**: constrained
sketches, timeline features, and named user parameters, aimed at producing
clean, human-editable parametric models.

The design is Fusion-first: tools are built around Fusion's own concepts
(feature timeline, sketch constraints, user parameters, components), not
adapted from any other CAD paradigm. Under the hood, the geometry-reading
layer reuses the platform-neutral
[`spatial-core`](https://github.com/aphollis/spatial-core) engine: a CAD
platform only has to provide two adapter functions (`bodies()` +
`tessellate()`), validated by that repo's JSON Schema conformance suite —
spatial understanding of B-Rep solids is the same no matter how the
geometry was authored.

```
Claude ──stdio── Node MCP server ──TCP 127.0.0.1:8767── Fusion add-in (Python)
                     └── spatial-core                        └── CustomEvent → main thread
```

**Status:** working end to end. Adapter conformance (F2) passed; six-question
spatial benchmark 6/6 (F3); parametric-bracket authoring acceptance passed
(F4): constrained sketch → extrude → hole → 2×2 pattern → fillet, six named
user parameters, resized purely via parameter driving, dimensions verified
numerically by the spatial tools.

## Setup

1. **Build the server** (Node 22+; the sibling
   [`spatial-core`](https://github.com/aphollis/spatial-core) repo must be
   cloned next to this one for the file: dependency):

   ```
   npm install
   npm run build
   ```

2. **Install the add-in** — link (or copy) `addin/FusionSpatialMCP` into
   Fusion's dev add-ins folder:

   ```powershell
   New-Item -ItemType Junction `
     -Path "$env:APPDATA\Autodesk\Autodesk Fusion 360\API\AddIns\FusionSpatialMCP" `
     -Target "<repo>\addin\FusionSpatialMCP"
   ```

3. **Run the add-in**: in Fusion press **Shift+S** → *Add-Ins* tab →
   **FusionSpatialMCP** → **Run**. The Text Commands palette logs
   `listener running on 127.0.0.1:8767`. Re-run after editing the add-in
   file. (Check *Run on Startup* to make it permanent.)

4. **Register the MCP server** with your client, e.g. for Claude Code:

   ```
   claude mcp add fusion -- node <repo>/dist/index.js
   ```

## Using it (agent workflow)

- **Orient first:** `fusion_document` — document, units, up-axis, and the
  feature timeline (in Fusion, the timeline IS the scene graph).
- **Any metric question** (size, position, distance, clearance, hollowness,
  wall thickness): use the `space_*` tools, never screenshots — they return
  exact numbers. `space_digest` inventories every body with kernel-exact
  volume/area/centroid; bodies get short handles (`b1`, `b2`, …).
- **Sub-body granularity**: `fusion_find_geometry` scans faces/edges
  analytically (find the ⌀3 holes: `kind='cylinder_face', radius=1.5`) and
  returns self-healing handles (`f1`, `e2`) that feed fillet/chamfer/sketch-
  plane/shell inputs and `fusion_measure_relation` — exact design-intent
  verdicts like "is this hole coaxial with that boss?" (Patterns adapted
  from [Fusion-Essentials](https://github.com/Philip-Mestenhauser/Fusion-Essentials),
  MIT/Apache-2.0.)
- **Authoring is parametric by default.** Every dimension input accepts a
  number (doc units), an expression (`"40 mm"`, `"width/2"`), or
  `{param: "wall_height", value: "40 mm"}` which creates a named user
  parameter on the fly. `fusion_create_sketch` takes entities + dimensions +
  constraints in one call and reports `fullyConstrained`;
  `fusion_add_feature` appends ONE timeline feature per call and returns a
  health report. **Editing = driving parameters**: `fusion_set_parameters`
  (batch, one recompute) or `fusion_edit_feature` (a feature's dimensions by
  role). `fusion_timeline` / `fusion_rollback` for history introspection and
  mid-history edits. `fusion_execute_api_script` is the escape hatch
  (`adsk`/`app`/`ui` preloaded, assign to `result`).
- Quality bar: *would a mechanical designer be happy to inherit this
  timeline?* Named features, named parameters, fully-constrained sketches.

## Tool surface

| Tool | Purpose |
|---|---|
| `fusion_document` | Orientation: doc, units, up-axis, timeline summary |
| `fusion_find_geometry` | Analytic sub-body scan: faces/edges/vertices by kind/radius/nearest, self-healing handles |
| `fusion_measure_relation` | Kernel-exact distance/angle + verdicts: coaxial, concentric, parallel, perpendicular, flush, clearance, touching |
| `fusion_get_selection` | What the user has selected ("this face/body") |
| `fusion_capture_viewport` | Viewport PNG (appearance; not for metrics) |
| `fusion_list_parameters` / `fusion_set_parameters` | Read / drive user + model parameters (batch, health report) |
| `fusion_create_sketch` | Sketch with entities + dimensions + constraints, returns profile ids |
| `fusion_add_feature` | One timeline feature: extrude, revolve, hole, fillet, chamfer, shell, patterns, mirror, combine |
| `fusion_edit_feature` | Edit a feature in place (parameters by role, suppress, rename) |
| `fusion_timeline` / `fusion_rollback` | Full history introspection / marker moves |
| `fusion_execute_api_script` | Python escape hatch on the main thread |
| `space_digest` | Metric inventory of all bodies |
| `space_measure` | distance / bbox / dims / point-probe |
| `space_relations` | Pairwise clearance, intersection, containment |
| `space_voxels` | ASCII occupancy layers (hollowness, mass distribution) |
| `space_section` | Planar cut: loops, areas, wall thickness |
| `space_views` | Labeled 4-tile orthographic PNG + legend |
| `space_fit` | Free-space placement search |
| `space_pick` | Identify the body under a `space_views` pixel |

## Development

- `node tools/call.mjs <method> [json | @file.py]` — raw wire calls
  (`ping`, `fusion.document`, `fusion.execute @script.py`, …)
- `npm run conformance` — adapter conformance suite (canonical contracts +
  suite live in the `spatial-core` package); must print `CONFORMANT`
- `node tools/f2-checks.mjs` — volumes vs. Fusion physical properties +
  world-space proxy tessellation (needs the `tools/f2-scene.py` scene)
- `node tools/f3-benchmark.mjs` — six-question spatial benchmark (≥5/6)
- `node tools/f4-bracket.mjs` — parametric bracket authoring acceptance
- `docs/BUILD_PLAN.md` — the phased build plan with the Fusion API traps
  (internal units are ALWAYS cm; face sketches flip normals; API rectangles
  have no constraints; …)

MIT licensed.