Fusion - the Fusion 360 Bridge

@@ -3,6 +3,11 @@ Autodesk and Anthropic shipped a **Fusion MCP server**: Fusion's own text-to-CAD surface, exposed over MCP. This bridge proxies it, so an Adom AI running in the cloud can use it. +**Does it do file search?** Yes, `fusion_mcp_read` with `queryType: "document"` searches, lists open,+and lists recent files across your projects. **Does it do electronics?** Yes, deeply,+`fusion_mcp_electronics_read` reads **49 electronics entity classes** (schematic, board, library, and+ERC/DRC errors) with field selection, filtering and pagination. Full detail below.+ ## Why the bridge has to proxy it  The MCP server is a **local HTTP/JSON-RPC endpoint**:@@ -11,122 +16,224 @@ The MCP server is a **local HTTP/JSON-RPC endpoint**: http://127.0.0.1:27182/mcp ``` -It binds **loopback on the user's machine** and was designed for Claude Desktop running on that-same machine. An Adom AI runs in a **cloud container** and cannot reach the user's `127.0.0.1` at-all.+It binds **loopback on the user's machine** and was designed for Claude Desktop running on that same+machine. An Adom AI runs in a **cloud container** and cannot reach the user's `127.0.0.1` at all. -The bridge already runs on that machine. So it is exactly the right proxy: these verbs hand a cloud-AI Autodesk's MCP tools without reimplementing any of them.+The bridge already runs on that machine. So it is the right proxy: these verbs hand a cloud AI+Autodesk's MCP tools without reimplementing any of them.  ## Turning it on -It is **off by default**, and there is **no API for the toggle** (verified by enumerating every-attribute on `apiPreferences`). The bridge turns it on for the user by driving the Preferences UI:+Off by default, and there is **no API for the toggle** (verified by enumerating `apiPreferences`).+The bridge turns it on by driving the Preferences UI:  ```bash adom-desktop fusion_mcp_enable '{}' ```  which opens Preferences, expands General, selects API, ticks-`Fusion MCP Server (runs locally on this device)`, clicks Apply then OK, and then **verifies the-port is listening** before reporting success.+`Fusion MCP Server (runs locally on this device)`, clicks Apply then OK, and verifies the port is+listening before reporting success.  ![The API page with the MCP server toggle](prefs-3-api-mcp.png) -Manual path, if you would rather: profile icon (top right) -> Preferences -> General -> API -> tick-the box -> Apply.- > ⛔ **The setting is discarded unless Apply is clicked.** Restarting or killing Fusion with the-> dialog open reverts it, and the port stays closed while the checkbox *looked* right. This is a-> real trap, it cost a debugging cycle here.--See [driving Fusion's preferences](fusion-preferences.md) for the general technique.+> dialog open reverts it, and the port stays closed while the checkbox looked right. This cost a+> debugging cycle. See [driving Fusion's preferences](fusion-preferences.md).  ## The handshake, which the bridge handles for you -The server speaks MCP **streamable-HTTP**, so a bare POST fails:+The server speaks MCP **streamable-HTTP**, so a bare POST fails with+`400 Missing MCP-Session-Id`. You must `initialize`, capture the `MCP-Session-Id` **response+header**, send `notifications/initialized`, then pass that header on every later call. The bridge+does all of it and silently re-establishes a dropped session. Confirmed live: protocol `2024-11-05`,+serverInfo `MCP Server Adapter 1.0.0`.++## The four tools++The surface is **four tools**, but the depth is in each tool's parameters. `read` is broad;+`execute` runs scripts and manages documents; `update` is undo/redo; `electronics_read` is a deep+read of the whole EAGLE object model. Call any of them through `fusion_mcp_call {tool, arguments}`. +---++### `fusion_mcp_read` (queryType): read, search, screenshot, introspect++Five query types, each with its own parameters.++**`queryType: "projects"`**, list every project in the current hub.+```bash+fusion_mcp_call '{"tool":"fusion_mcp_read","arguments":{"queryType":"projects"}}'+# -> {"projects":[{"name":"Main","id":"..."}, ...]}   (verified live: 16 projects) ```-400  {"error": "Missing MCP-Session-Id header"}++**`queryType: "document"` + `operation`**, this is the **file search / open / recent** surface.++| operation | what it does | params |+|---|---|---|+| `search` | fuzzy, case-insensitive file-name search across projects (or one) | `name` (required), `project` (optional) |+| `open` | list currently OPEN documents (`isActive`, `isModified`) | none |+| `recent` | list recently opened documents | none |++```bash+fusion_mcp_call '{"tool":"fusion_mcp_read","arguments":{"queryType":"document","operation":"search","name":"wire bender"}}'+# -> {"results":[{"name":"Wire Bender","id":"urn:..."}, ...]} ```+The `id` it returns is what `fusion_mcp_execute` `document`/`open` takes to open the file. -You must `initialize`, capture the `MCP-Session-Id` **response header**, send-`notifications/initialized`, then pass that header on every later call. The bridge does all of it-and silently re-establishes a dropped session, so you never see it.+**`queryType: "apiDocumentation"`**, search Fusion's own API docs. This is how the AI learns the+API before writing a script. -Handshake confirmed live: protocol `2024-11-05`, serverInfo `MCP Server Adapter 1.0.0`.+| param | meaning |+|---|---|+| `searchPattern` (required) | regex over class / member names |+| `apiCategory` | `class` \| `member` \| `description` \| `all` |+| `filter` | dotted namespace/class limit, e.g. `adsk.fusion.Extrude` | -## The verbs+```bash+fusion_mcp_call '{"tool":"fusion_mcp_read","arguments":{"queryType":"apiDocumentation","searchPattern":"Extrude","apiCategory":"class"}}'+``` -| verb | what it does |+**`queryType: "screenshot"`**, render a PNG of the active view (base64), from any view-cube angle.+Lets the AI *see* the model.++| param | meaning | |---|---|-| `fusion_mcp_status` | is it up? serverInfo + live tool list |-| `fusion_mcp_enable` | turn it on via the Preferences UI, then verify the port |-| `fusion_mcp_tools` | full tool list **with input schemas**, for building a valid call |-| `fusion_mcp_call` | call any tool: `{tool, arguments, timeout}` |-| `fusion_mcp_resources` | list resources, or read one by `uri` |+| `direction` | `current`, `front`, `back`, `top`, `bottom`, `left`, `right`, `iso-bottom-left`, `iso-bottom-right`, `iso-top-left`, `iso-top-right` |+| `width` / `height` | 32-4096 px (default: canvas size) |+| `antiAliasing` | default true |+| `transparentBackground` | default true | -## What Autodesk exposes+**`queryType: "activeCommand"`**, read the currently open command dialog: its id, name, tooltip,+and every visible input (values, checkboxes, dropdowns with their enum, selections, tables). Returns+`{"activeCommand": null}` when no dialog is open. Use it to read the live state of a command mid-edit. -Four tools:+--- -| tool | args | what it does |-|---|---|---|-| `fusion_mcp_read` | `queryType`, `apiCategory`, `filter`, `name`, `operation`, `project`, `direction`, `height`, `antiAliasing` | read geometric properties and data from the active model |-| `fusion_mcp_update` | `featureType` | update the active model |-| `fusion_mcp_execute` | `featureType`, `object` | execute operations in the active model |-| `fusion_mcp_electronics_read` | `entity_type`, `object` | read Electronics design data (schematic, board, library) |+### `fusion_mcp_execute` (featureType): run scripts, open/close/save documents -`fusion_mcp_electronics_read` is the interesting one for us. Its `entity_type` covers the whole-EAGLE-derived object model: `electronics.Board`, `electronics.Element`, `electronics.Contact`,-`electronics.ContactRef`, `electronics.Device`, `electronics.DeviceSet`, `electronics.Gate`,-`electronics.Bus`, `electronics.Error` (ERC/DRC), `electronics.Frame`, `electronics.Grid`,-`electronics.Attribute`, `electronics.Dimension`, `electronics.Circle` and more.+**`featureType: "script"`**, the real text-to-CAD power: run **arbitrary Python** against the Fusion+API in the live design. -Plus resources describing those schemas:+- The script must define `def run(_context):` as the entry point.+- Anything it `print()`s comes back as the tool output; any exception comes back as the error.+- Do **not** catch exceptions in `run` (you lose the failure location). Read the API docs first+  (`read`/`apiDocumentation`), then verify with a `read`/`screenshot` afterwards. +```bash+fusion_mcp_call '{"tool":"fusion_mcp_execute","arguments":{"featureType":"script",+  "object":{"script":"import adsk.core\ndef run(_c):\n    print(adsk.core.Application.get().version)\n"}}}' ```-resource://mcp.electronics_entity_types-resource://mcp.electronics_schema_board-resource://mcp.electronics_schema_contact-...++**`featureType: "document"` + `operation`**, file lifecycle.++| operation | what it does | params |+|---|---|---|+| `open` | open a file by id | `fileId` (from `read`/`document`/`search`) |+| `close` | close the active document | `userConfirmedSaveAndClose` or `userConfirmedCloseWithoutSave` if it has unsaved changes |+| `save` | save the active document | **only when the user explicitly asks** |++---++### `fusion_mcp_update` (featureType): undo / redo++That is the whole tool: `{"featureType":"undo"}` or `{"featureType":"redo"}`. Each returns+`success` plus `canUndo` / `canRedo`. Fails gracefully mid-preview or during an interactive command.+There is **no create/modify-feature verb here**; geometry authoring goes through `execute`/`script`.++---++### `fusion_mcp_electronics_read` (entity_type): the whole EAGLE object model, read-only++Requires an active Electronics document. Pass one `entity_type`; optionally an `object` with+`fields`, `filters`, and `pagination`. **49 classes**, grouped:++| group | classes |+|---|---|+| **Schematic** | `Schematic`, `Sheet`, `Net`, `Bus`, `Segment`, `Junction`, `Wire`, `Label`, `Instance`, `Part`, `PinRef`, `Module`, `ModuleInstance`, `Port`, `PortRef`, `Variant`, `VariantDef` |+| **Board** | `Board`, `Signal`, `Pad`, `Via`, `Smd`, `Hole`, `PolyPour`, `PolyShape`, `PolyCutout`, `Spline`, `Layer`, `Element`, `NetClass`, `Dimension` |+| **Library** | `Library`, `Device`, `DeviceSet`, `Symbol`, `Package`, `Package3D`, `Pin`, `Gate`, `Contact`, `ContactRef`, `Technology` |+| **Shared graphics** | `Circle`, `Rectangle`, `Text`, `Frame`, `Grid` |+| **Design checks** | `Error` (each ERC or DRC error/warning) |+| **Attributes** | `Attribute` (name/value on any parent) |++**Query shape:**+```json+{ "entity_type": "electronics.<Class>",+  "object": { "fields": ["name", "..."],+              "filters": [{"property": "name", "op": "eq", "value": "GND"}],+              "pagination": {"limit": 100, "offset": 0} } } ``` +Each class has a schema listing its properties, their types, and which are filterable plus the+allowed operators. For example, `electronics.Net` exposes `object_id`, `sheet_object_id`, `name`,+`column`, `row`, `net_class_number`, with `eq` on most and `eq`/`lt`/`gt` on the numeric class index.+ ```bash-adom-desktop fusion_mcp_resources '{}'-adom-desktop fusion_mcp_resources '{"uri":"resource://mcp.electronics_entity_types"}'+# all nets named GND+fusion_mcp_call '{"tool":"fusion_mcp_electronics_read","arguments":{"entity_type":"electronics.Net","object":{"filters":[{"property":"name","op":"eq","value":"GND"}]}}}'+# every DRC/ERC error+fusion_mcp_call '{"tool":"fusion_mcp_electronics_read","arguments":{"entity_type":"electronics.Error"}}'+# board signals, names only+fusion_mcp_call '{"tool":"fusion_mcp_electronics_read","arguments":{"entity_type":"electronics.Signal","object":{"fields":["name"]}}}' ``` -## Calling a tool+This is **read-only**: MCP reads the electronics design, it does not author it. To change a board,+use EAGLE commands through the native `fusion_electron_run` (see [2D board layout](board-layout-2d.md)).++## Resources: the per-class schemas++The server also exposes **50 resources**, the discovery layer for `electronics_read`:++- `resource://mcp.electronics_entity_types`, all entity types with active-workspace hints+- `resource://mcp.electronics_schema_<class>`, one class's properties, types, and filter operators+  (49 of these, one per class)  ```bash-adom-desktop fusion_mcp_tools '{}'                      # get the input schemas first-adom-desktop fusion_mcp_call '{"tool":"fusion_mcp_electronics_read",-                               "arguments":{"entity_type":"electronics.Element"}}'+fusion_mcp_resources '{}'                                                # list all 50+fusion_mcp_resources '{"uri":"resource://mcp.electronics_schema_net"}'   # read one schema ``` -MCP acts on the **active Fusion document**, so open one first (`fusion_aps_open`). A complaint about-no active document usually means nothing is open, not that the call was malformed.+Read the schema for a class before filtering on it, so you use a property that exists and an+operator it supports.++## What the four tools add up to++| capability | how |+|---|---|+| Find a cloud file | `read` / `document` / `search` |+| Open / list open / recent | `execute` document/open, `read` document/open/recent |+| List projects | `read` / `projects` |+| See the model | `read` / `screenshot` (any view-cube direction) |+| Learn the API | `read` / `apiDocumentation` |+| Read a live command dialog | `read` / `activeCommand` |+| Author geometry (text-to-CAD) | `execute` / `script` (arbitrary Python) |+| Undo / redo | `update` |+| Save / close | `execute` / `document` |+| Read schematic / board / library | `electronics_read` (49 classes) |  ## MCP tools vs this bridge's verbs  They complement each other; neither replaces the other.  **Prefer a native `fusion_*` verb when one exists.** They are tested here, they carry hints that-teach the calling AI what to do next, they handle the awkward parts (kit-aware BOM counting, the-2-minute sign-in clock, GLB optimization), and they work whether or not the user has enabled MCP or-holds a Fusion subscription.+teach the next step, they handle the awkward parts (kit-aware BOM counting, the 2-minute sign-in+clock, GLB optimization), and they work whether or not MCP is enabled or the user holds a Fusion+subscription. Notably, this bridge already gives you **fast APS cloud search**+([APS cloud search](aps-cloud-search.md)), **manufacturing exports**, and a **mechanical BOM**+([mechanical BOM](mechanical-bom.md)) that MCP does not. -**Reach for MCP** when you want Autodesk's own text-to-CAD surface: natural-language geometry-creation, feature execution, and the structured Electronics object model, which is richer for-querying a board than anything hand-rolled here.+**Reach for MCP** for Autodesk's own text-to-CAD (`execute`/`script`), model screenshots, live+command introspection, and the structured Electronics object-model read, which is richer for+querying a board's connectivity than anything hand-rolled.  ## Requirements and limits  - **Fusion subscription.** Autodesk gates the MCP server to subscribers.-- **Fusion must be running.** The server lives inside Fusion; if it is not running, the port is-  closed.+- **Fusion must be running.** The server lives inside Fusion; if it is not running, the port is closed. - **Loopback only**, hence this proxy.+- **Reads, mostly.** `execute`/`script` can author geometry, but `update` is only undo/redo and+  `electronics_read` is read-only; MCP is not a full write API for electronics. - The toggle is UI-only, so `fusion_mcp_enable` briefly uses the foreground and says why.  ## Sources