@rui.branco/revit-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rui Branco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,496 @@
+# revit-mcp
+
+[![Revit](https://img.shields.io/badge/Revit-2025%20%7C%202026%20%7C%202027-006666)](https://www.autodesk.com/products/revit/overview)
+[![Platform](https://img.shields.io/badge/platform-Windows-0078D4)](#installation)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A518-339933)](https://nodejs.org)
+[![Tests](https://img.shields.io/badge/tests-507%20passing-success)](#development)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Drive Autodesk Revit from Claude.** Query the model open on your desktop, edit
+it, and produce a full drawing set in plain language — levels and elements,
+sheets and schedules, views and PDF exports.
+
+**Windows · Revit 2025, 2026 or 2027 · Node.js 18+.** The Revit add-in ships
+precompiled, so there is nothing to build and no .NET SDK to install. `npm` is
+never run at startup — the Desktop extension carries its dependencies, and the
+Claude Code route fetches the package once via `npx`.
+
+## Installation
+
+### 1. Register the server
+
+#### Claude Desktop — extension
+
+1. **[⬇ Download `revit-mcp.mcpb`](https://github.com/rui-branco/revit-mcp/releases/latest/download/revit-mcp.mcpb)**
+2. In Claude Desktop, open **Settings → Extensions**
+3. **Drag the `.mcpb` file onto that window**, then press **Install**
+
+No JSON to edit and nothing to download at runtime: the extension carries the
+server, its dependencies and the Revit add-in. Bridge URL and request timeout
+are exposed as settings under **Settings → Extensions → Revit**.
+
+> Double-clicking the file only works if Claude Desktop has registered the
+> `.mcpb` file type; on many installs it has not, so use the drag-and-drop step
+> above.
+
+<details>
+<summary>Or configure it by hand</summary>
+
+Open **Settings → Developer → Edit Config** (that is
+`%APPDATA%\Claude\claude_desktop_config.json`) and add the `revit` entry,
+keeping any servers already there:
+
+```json
+{
+  "mcpServers": {
+    "revit": {
+      "command": "npx",
+      "args": ["-y", "github:rui-branco/revit-mcp"]
+    }
+  }
+}
+```
+
+Then **quit Claude Desktop from the system tray** — closing the window is not
+enough — and reopen it.
+
+If the server shows as failed, Claude Desktop could not find `npx` on its
+`PATH`. Use absolute paths instead (`where.exe npx.cmd` prints yours), or point
+`command` at your `node.exe` with `args` of
+`["C:\\path\\to\\revit-mcp\\index.js"]`.
+
+</details>
+
+#### Claude Code — one command
+
+```bash
+claude mcp add revit --scope user -- npx -y github:rui-branco/revit-mcp
+```
+
+`--scope user` enables it in every project; `--scope project` writes it to the
+repo's `.mcp.json` instead, to share with a team. Check it with `claude mcp list`.
+
+<details>
+<summary><b>Other MCP clients</b></summary>
+
+Any stdio MCP client works. Use `npx -y github:rui-branco/revit-mcp` as the
+server command; it takes no arguments and needs no environment beyond the
+optional [configuration](#configuration).
+
+</details>
+
+### 2. Install the Revit add-in
+
+Ask Claude to **install the Revit bridge**. That runs `revit_install_bridge`,
+which copies the add-in and its `.addin` manifest into
+`%APPDATA%\Autodesk\Revit\Addins\<version>\` for every Revit it finds. Revit
+need not be running, and re-running is safe.
+
+### 3. Restart Revit and approve the add-in
+
+Revit scans the Addins folder only at startup. On first load it shows a
+**"Security - Unsigned Add-In"** dialog for `RevitMcpBridge` — this is expected,
+the add-in is not code-signed. Choose **Always Load**; *Do Not Load* is
+remembered and the bridge will never start.
+
+### 4. Verify
+
+Open a model and ask Claude to run `revit_status`. It reports the bridge
+version, Revit version and active document, confirming the chain end to end.
+
+<details>
+<summary><b>Installing manually, or uninstalling</b></summary>
+
+From the package's `revit-bridge` directory:
+
+```powershell
+.\install.ps1
+```
+
+| Flag | Effect |
+| --- | --- |
+| `-RevitVersion 2026` | Only that version, even outside the default Program Files location. |
+| `-Build` | Compile a fresh add-in with `dotnet build -c Release`. Needs the .NET SDK. |
+| `-SkipBuild` | Never build. Already the default when the bundled add-in is present. |
+| `-Uninstall` | Remove the manifest and the install folder. |
+| `-Json` | Emit one JSON result object as the only stdout output — the mode the MCP tools use. |
+
+Exit codes: `0` success, `1` unhandled failure, `2` no Revit found, `3` no
+supported Revit version, `4` build failed or .NET SDK missing, `5` no add-in to
+install. Runs under Windows PowerShell 5.1 and PowerShell 7.
+
+To uninstall: ask Claude to uninstall the Revit bridge
+(`revit_uninstall_bridge`) and restart Revit, then `claude mcp remove revit` or
+delete the entry from `claude_desktop_config.json`.
+
+</details>
+
+<details>
+<summary><b>Version support and prerequisites</b></summary>
+
+| | |
+| --- | --- |
+| **OS** | Windows (Revit has no macOS build) |
+| **Revit** | 2025, 2026 or 2027 |
+| **Node.js** | 18 or newer |
+| **.NET SDK** | Not required — only to build the C# side yourself |
+
+One prebuilt add-in covers all three Revit versions: it is compiled against the
+Revit 2025 reference assemblies, which load unchanged in 2026 and 2027. Tested
+end to end against Revit 2027.3. **Revit LT is unsupported** (no add-in API) and
+**2024 and earlier are refused** (.NET Framework 4.8 cannot load a
+`net8.0-windows` assembly).
+
+</details>
+
+## Usage
+
+With a model open in Revit, ask in plain language:
+
+```
+What levels are in this model?
+How many walls are there, and what types?
+Add a level at 3 m and a second at 6 m.
+Set Comments to "reviewed" on everything I have selected.
+Create sheets L.02.001 through L.02.010 with the A0 title block.
+Make a plan of each level at 1:100 and place it on its sheet.
+Schedule the planting by type, with quantities, and put it on L.09.017.
+Export every sheet to one PDF.
+```
+
+Two habits worth keeping:
+
+- Ask for **one phase per call** — all ten sheets in one request, not ten
+  requests. Each call is one undo step.
+- After a batch of writes, ask for `revit_diagnostics`. Warnings the bridge
+  resolved silently are recorded there and nowhere else.
+
+## Features
+
+- **Query the model** — levels, categories, element filters, selection, and
+  parameters, with paging and total counts.
+- **Edit the model** — create levels, walls, floors, toposolids and pipes,
+  place families, planting and openings, set parameters, delete elements.
+- **Build drawings** — sheets, views, sections, plans, legends, schedules,
+  title blocks, and sheet collections.
+- **Control graphics** — view templates, category overrides, crop regions,
+  display styles, sun and background settings.
+- **Export** — view images and native multi-sheet PDFs.
+- **Runs unattended** — modal dialogs and transaction warnings are answered by
+  the bridge and recorded for you to read back.
+- **Hot reload** — rebuild the C# endpoints and reload them into a running
+  Revit with the model still open.
+- **One call, one undo step** — every write is a single transaction group.
+
+## Tools
+
+88 tools, grouped below; every write is one undo step.
+
+### Conventions
+
+- Units are Revit internal units (decimal feet) in both directions, unconverted: a level at 3 m is `9.8425`.
+- `revit_query_elements` caps at 500 rows (default 100) and always returns the total match count.
+- `revit_get_elements` returns only the parameters named in `params`; without it, identity fields only.
+- One tool call is one undo step: each write is a transaction group, assimilated on success, rolled back on failure.
+- `revit_create_sheets` skips sheet numbers that already exist rather than failing, so re-running is safe.
+- A view lives on exactly one sheet; a placed view returns `VIEW_ALREADY_PLACED`, so use `revit_duplicate_view`.
+
+<details>
+<summary><b>Status &amp; diagnostics</b> (4 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_status` | Returns bridge status, Revit version, units, user, and the active document (`null` when none). |
+| `revit_diagnostics` | Lists dialogs the bridge answered and warnings it resolved; check after a batch of writes. |
+| `revit_set_auto_dismiss` | Toggles dialog auto-dismiss at runtime, optionally clearing the diagnostics buffer. |
+| `revit_get_warnings` | Reads the warnings the model carries right now — Revit's own Review Warnings list. |
+
+</details>
+
+<details>
+<summary><b>Query &amp; read</b> (6 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_list_levels` | Lists every level in the model as `{ id, name, elevation }`. |
+| `revit_list_categories` | Lists every category present in the model with its element count, busiest first. |
+| `revit_query_elements` | Filters elements by category, level and type name with `limit`/`offset`; returns the total. |
+| `revit_get_elements` | Returns rows for specific element ids, carrying only the parameters named in `params`. |
+| `revit_get_selection` | Returns what the user currently has selected in the Revit UI. |
+| `revit_inspect_elements` | Measures elements: geometry, bounds and placement that `revit_get_elements` leaves out. |
+
+</details>
+
+<details>
+<summary><b>Document &amp; project</b> (5 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_new_project` | Creates and opens a project from an `.rte` template; `overwrite: true` rebuilds it in place. |
+| `revit_open_project` | Opens an existing `.rvt` as the active document; works with no document open. |
+| `revit_save` | Saves the active document in place; a never-saved model returns `NOT_SAVEABLE`. |
+| `revit_save_as` | Saves the active document to a new path; refuses an existing file unless `overwrite` is true. |
+| `revit_close_project` | Closes the active document, activating another first; discards changes unless `save` is true. |
+
+</details>
+
+<details>
+<summary><b>Parameters &amp; element edits</b> (5 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_set_parameters` | Sets one named instance parameter to one value across a batch of element ids. |
+| `revit_create_project_parameter` | Creates a project parameter and binds it to categories; an existing binding is reported, not an error. |
+| `revit_set_sheet_parameters` | Writes a different parameter value per sheet in one call; sheets missing it come back as `failed`. |
+| `revit_delete_elements` | Deletes elements by id; Revit may remove dependents, so the count can exceed the request. |
+| `revit_move_elements` | Moves elements by a vector in feet without rebuilding them. |
+
+</details>
+
+<details>
+<summary><b>Geometry &amp; modelling</b> (10 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_create_levels` | Creates levels from a list of `{ name, elevation }` pairs. |
+| `revit_create_walls` | Creates walls on a level from a wall type, a height and a list of `{ start, end }` curves. |
+| `revit_create_toposolid` | Builds the site surface from survey points, as a Toposolid or a legacy TopographySurface. |
+| `revit_flatten_toposolid` | Levels a region of the site surface to one elevation and reports the residual error. |
+| `revit_create_floor` | Creates a floor from a closed boundary at the level's elevation; `offset` lifts it off the level. |
+| `revit_create_directshape` | Builds elements from raw solids with no family: cylinder, box, sphere, cone, extrusion. |
+| `revit_place_planting` | Creates one Planting element per point, a trunk cylinder with a crown sphere; no family needed. |
+| `revit_create_pipes` | Models pipe runs as geometry, one element per run and a cylinder per segment; no MEP family. |
+| `revit_place_sprinklers` | Places one sprinkler head element per point and reports the category Revit allowed. |
+| `revit_excavate_toposolid` | Cuts a toposolid with the elements sunk into it — a pool, a basement — via `Toposolid.ExcavateBy`. |
+
+</details>
+
+<details>
+<summary><b>Families &amp; content</b> (4 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_load_families` | Loads `.rfa` files into the project, returning family names and type ids; reloading is safe. |
+| `revit_list_family_symbols` | Lists the family types loaded in the model, filtered by `category`, `family_name`, or both. |
+| `revit_place_families` | Places one family instance per point; `z` is an absolute model elevation, read back per point. |
+| `revit_place_openings` | Places doors and windows in walls; without `host_wall_id`, hosts in the nearest wall within 3 feet. |
+
+</details>
+
+<details>
+<summary><b>Materials &amp; types</b> (8 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_list_materials` | Lists every material as `{ id, name, colorRgb, appearanceAssetId }`. |
+| `revit_create_material` | Creates a material with colour, transparency, shininess and an optional `texture_path`. |
+| `revit_set_material_texture` | Puts a bitmap on a material with `scale` (tile size in feet), `rotation` and `tint`. |
+| `revit_assign_material` | Assigns an existing material through the type's compound structure or a material parameter. |
+| `revit_create_wall_type` | Creates a wall type carrying a material and a thickness by duplicating an existing type. |
+| `revit_create_floor_type` | Creates a floor type carrying a material and a thickness by duplicating an existing type. |
+| `revit_get_material_appearance` | Reads the appearance asset behind a material — the rendered look, not the shading colour. |
+| `revit_set_material_appearance` | Edits a material's appearance asset by naming the properties to write. |
+
+</details>
+
+<details>
+<summary><b>Views</b> (10 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_list_views` | Lists every non-template view with its type, sheet placement and direction vectors. |
+| `revit_create_plan_view` | Creates a plan on a level; `view_family_type` names the Site, Ceiling or Structural plan type. |
+| `revit_create_drafting_view` | Creates a drafting view: linework and notes, no model geometry. |
+| `revit_create_3d_view` | Creates an isometric or perspective 3D view from `eye`/`target`; returns `modelExtents`. |
+| `revit_create_section_view` | Creates a section from an origin, a look direction, and width/height/depth in feet. |
+| `revit_list_legends` | Lists the legend views as `{ id, name, scale }`; empty means the document has none. |
+| `revit_create_legend` | Creates a legend by duplicating an existing one, else `NO_LEGEND_TO_DUPLICATE`. |
+| `revit_duplicate_view` | Duplicates a view as Duplicate, WithDetailing or AsDependent. |
+| `revit_set_view_scale` | Sets 1:X on one view or a batch; a perspective view returns `PERSPECTIVE_VIEW_HAS_NO_SCALE`. |
+| `revit_scale_perspective_crop` | Resizes a perspective view on its sheet with proportions locked; the camera is untouched. |
+
+</details>
+
+<details>
+<summary><b>View graphics &amp; templates</b> (14 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_set_view_style` | Sets a view's display style and detail level, both read back off the view. |
+| `revit_set_view_background` | Sets a 3D view's background to `sky`, `gradient` or `image`; a non-3D view is a `BAD_REQUEST`. |
+| `revit_hide_view_categories` | Hides categories in one view; `['annotation']` is shorthand for levels, grids, sections and more. |
+| `revit_override_view_categories` | Overrides category line colour, weight and transparency in one view; `dry_run` defaults to true. |
+| `revit_set_view_sun` | Moves the sun by `azimuth`/`altitude` in degrees or by `date`/`time`; settings can be shared. |
+| `revit_get_view_graphics` | Returns style, detail level, template, shadow sliders, background and a cast-shadows probe. |
+| `revit_set_view_graphics` | Sets style, detail level, shadow/sunlight intensity and cast shadows in one undo step. |
+| `revit_get_view_graphics_command_status` | Reports what became of the last posted shadows command, with a fresh parameter probe. |
+| `revit_capture_view_template` | Turns a view into a view template controlling `graphics`, `shadows` or `all`. |
+| `revit_apply_view_template` | Applies or assigns one template to many views, validated first; `dry_run` defaults to true. |
+| `revit_list_view_templates` | Lists view templates with id, name, view type, and the parameters each one controls. |
+| `revit_get_view_crop` | Reads the crop of one view or a batch: whether it is on, drawn, and where it sits. |
+| `revit_set_view_crop` | Crops one view or a batch to a region of the model, in feet. |
+| `revit_hide_elements_in_view` | Hides elements permanently in one view — the 'Hide in View > Elements' override. |
+
+</details>
+
+<details>
+<summary><b>Sheets &amp; title blocks</b> (11 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_list_titleblocks` | Lists the title block family types loaded in the model, the source of the title block id. |
+| `revit_inspect_titleblock_family` | Reads what a title block prints: logo, placeholders, labels and their paper sizes. |
+| `revit_edit_titleblock_family` | Edits a title block family: strip logos and placeholders, retext, resize labels, add notes. |
+| `revit_list_sheets` | Lists every sheet as `{ id, number, name }`, ordered by sheet number. |
+| `revit_create_sheets` | Creates sheets from `{ number, name }` pairs; numbers that exist are skipped and reported. |
+| `revit_place_views_on_sheets` | Places views on sheets in one batch, handling schedules as schedule instances. |
+| `revit_get_sheet_layout` | Measures where everything on a sheet actually sits, in feet on the paper. |
+| `revit_set_viewport_position` | Moves one viewport on its sheet. |
+| `revit_list_sheet_collections` | Lists the sheet collections — the collapsible groups under Sheets in the Project Browser. |
+| `revit_set_sheet_collections` | Puts sheets into native sheet collections so the browser shows collapsible groups. |
+| `revit_get_browser_organization` | Inspects how the Project Browser currently groups the Sheets section. |
+
+</details>
+
+<details>
+<summary><b>Schedules &amp; annotation</b> (6 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_create_schedule` | Creates a schedule for a category with named fields; unknown names are skipped and listed. |
+| `revit_configure_schedule` | Sets itemisation, grouping, sorting, totals, headings and widths; `dry_run` defaults to true. |
+| `revit_set_schedule_position` | Moves a schedule instance on a sheet by its top-left corner; `dry_run` defaults to true. |
+| `revit_draw_detail_lines` | Draws detail lines in a drafting view or plan; an unknown line style falls back and is reported. |
+| `revit_add_text_notes` | Adds text notes to a view; `size` is paper feet and duplicates a text type when needed. |
+| `revit_read_schedule` | Reads the text of a schedule, cell by cell. |
+
+</details>
+
+<details>
+<summary><b>Export</b> (2 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_export_view_image` | Exports views to PNG/JPEG; Revit renames the file, so open the returned `path`. |
+| `revit_export_pdf` | Exports named views and sheets through Revit's own PDF exporter — vector, at real sheet size. |
+
+</details>
+
+<details>
+<summary><b>Bridge install &amp; reload</b> (3 tools)</summary>
+
+| Tool | Description |
+| --- | --- |
+| `revit_install_bridge` | Installs the bundled add-in into Revit's Addins folder; works with Revit closed. |
+| `revit_reload_bridge` | Reloads the add-in's endpoint logic from disk without restarting Revit. |
+| `revit_uninstall_bridge` | Removes the add-in and its manifest from Revit's Addins folder. |
+
+</details>
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `REVIT_MCP_URL` | `http://localhost:48884/revit-mcp` | Bridge base URL. Change it for a second Revit instance. |
+| `REVIT_MCP_TIMEOUT` | `30000` | Per-request timeout, in milliseconds. |
+| `REVIT_MCP_BRIDGE_TIMEOUT_MS` | `30000` | Read by the add-in: how long a request waits for Revit's main thread. Clamped to 1–600 s. |
+
+## Unattended operation
+
+A modal dialog parks Revit's main thread, and the bridge can only run work when
+that thread goes idle — so with nobody at the keyboard, one dialog would fail
+every call from then on. The bridge therefore answers them itself:
+
+- **Dialogs are auto-dismissed** (on by default). Ordinary dialogs get OK;
+  anything that sounds destructive — delete, remove, overwrite, discard, unload,
+  save, close — gets Cancel.
+- **Transaction warnings are resolved** by a failure preprocessor: Revit's own
+  resolution where one exists, otherwise the warning is deleted. Genuine
+  **errors** are never suppressed — they fail the transaction and roll it back.
+
+**`revit_diagnostics` is the other half of that trade.** A silently resolved
+warning often means the model did something you did not ask for. Every
+dismissed dialog and resolved warning goes to a 200-entry ring buffer, readable
+only there. Check it after a batch of writes; `revit_set_auto_dismiss` with
+`clear: true` empties it first so the next read covers only that batch.
+
+Turn auto-dismiss **off** (`revit_set_auto_dismiss`, `enabled: false`) when
+someone is working in Revit at the same time. Calls then fail with `REVIT_BUSY`
+until the dialog is answered by hand.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `connection refused` | Revit is not running, or is running without the add-in. | Start Revit. Check `%APPDATA%\Autodesk\Revit\Addins\<version>\` for `RevitMcpBridge.addin`. If the dialog was answered *Do Not Load*, reinstall and choose **Always Load**. |
+| `HTTP 404 … add-in is not loaded` | Manifest present, assembly failed to load. | The DLL was blocked by Windows (file properties → **Unblock**), or a stale install. Reinstall, restart Revit. Log: `%LOCALAPPDATA%\RevitMcpBridge\bridge.log`. |
+| `did not answer within Nms` | Revit is busy or showing a modal dialog. | Check `revit_diagnostics` — a dialog seen but unanswered is recorded with `answered: false`. Otherwise clear the screen in Revit and retry, or raise `REVIT_MCP_TIMEOUT`. A timed-out write may still have completed. |
+| `no active document` | Revit is on the start page or between documents. | Open a model and retry. `revit_status` deliberately tolerates this, which distinguishes it from the others. |
+
+## Security
+
+- The add-in runs **inside `Revit.exe` with full Revit API access**. It can
+  read, modify and delete anything in the open model, and open, save or close
+  documents. There is no read-only mode.
+- It opens an HTTP listener bound to the `127.0.0.1` literal (not a wildcard) on
+  port `48884`. Not reachable from the network, but **unauthenticated**: any
+  local process can drive your Revit session.
+- The add-in is **not code-signed**, hence Revit's unsigned add-in dialog.
+- **Auto-dismiss answers Revit's dialogs for you.** Turn it off when you are at
+  the keyboard, and read `revit_diagnostics` after writes.
+- **Work on a copy** of any model you care about.
+
+Report a vulnerability privately through
+[GitHub security advisories](https://github.com/rui-branco/revit-mcp/security/advisories/new).
+
+## Development
+
+```bash
+git clone https://github.com/rui-branco/revit-mcp.git
+cd revit-mcp
+npm install
+npm test
+```
+
+`npm test` is `node --test` over `tests/` — 507 tests. It touches no Revit and
+opens no socket: the HTTP layer is stubbed and the tools are exercised through a
+real MCP client over an in-memory transport.
+
+The C# side needs the **.NET SDK** (end users do not):
+
+```bash
+npm run build:bridge          # dotnet build -c Release, then refresh revit-bridge/dist/
+cd revit-bridge && .\install.ps1 -Build   # install that local build
+```
+
+`revit-bridge/dist/` is the compiled add-in that ships with the package, and is
+committed on purpose — that is what spares end users the SDK. `prepublishOnly`
+re-runs `build:bridge` and the tests, so a stale binary cannot be published.
+
+The add-in is **two assemblies**: `RevitMcpBridge.dll` is the loader Revit pins
+for the session (HTTP listener, main-thread pump, dialog handling), and
+`RevitMcpBridge.Handlers.dll` is the routing and endpoint logic, loaded into a
+collectible `AssemblyLoadContext` from a shadow copy. One build produces both.
+
+That split is what makes **hot reload** work: rebuild, call
+`revit_reload_bridge`, and the new logic is live with the model still open. If
+the response reports `unloadedPrevious: false` the new logic is still live, but
+the old context is leaking and is worth a look.
+
+### Further reading
+
+| Document | Covers |
+| --- | --- |
+| [`revit-bridge/README.md`](revit-bridge/README.md) | Add-in internals: the `ExternalEvent` pump, the transaction model, the full HTTP contract. |
+| [`docs/documentation.md`](docs/documentation.md) | Sheets, schedules and drawing-set production. |
+| [`docs/professional-graphics.md`](docs/professional-graphics.md) | View templates, category overrides, display styles. |
+| [`docs/professional-qa.md`](docs/professional-qa.md) | Warnings, bounds and drawing-set QA. |
+
+## Contributing
+
+Issues and pull requests are welcome. Please run `npm test` before opening a PR,
+and `npm run build:bridge` as well if you changed the C# side.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/index.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { pathToFileURL } from "url";
+import { createBridge } from "./lib/bridge.js";
+import { registerReadTools } from "./lib/tools/read.js";
+import { registerWriteTools } from "./lib/tools/write.js";
+import { registerParameterTools } from "./lib/tools/parameters.js";
+import { registerModelTools } from "./lib/tools/model.js";
+import { registerGeometryTools } from "./lib/tools/geometry.js";
+import { registerMaterialTools } from "./lib/tools/materials.js";
+import { registerMaterialAppearanceTools } from "./lib/tools/material-appearance.js";
+import { registerDocumentTools } from "./lib/tools/document.js";
+import { registerSheetTools } from "./lib/tools/sheets.js";
+import { registerSheetCollectionTools } from "./lib/tools/sheet-collections.js";
+import { registerTitleblockTools } from "./lib/tools/titleblocks.js";
+import { registerViewTools } from "./lib/tools/views.js";
+import { registerGraphicsTools } from "./lib/tools/graphics.js";
+import { registerDetailTools } from "./lib/tools/detail.js";
+import { registerDocumentationTools } from "./lib/tools/documentation.js";
+import { registerDiagnosticsTools } from "./lib/tools/diagnostics.js";
+import { registerQualityTools } from "./lib/tools/quality.js";
+import { registerReloadTools } from "./lib/tools/reload.js";
+import { registerInstallTools } from "./lib/tools/install.js";
+
+const instructions = `# Revit MCP
+
+This MCP drives the model that is open in Autodesk Revit on this machine. Node
+talks to a bridge add-in running inside Revit over HTTP on localhost.
+
+## When to use these tools
+
+Use these tools whenever the user wants to:
+- Ask about the open model (e.g. "what levels are there", "how many walls", "what's selected")
+- Read parameters off elements (e.g. "what's the Mark on these doors")
+- Change the model (e.g. "add a level at 3m", "set Comments on the selection")
+- Populate a project (e.g. "build the site surface", "pave the terrace", "plant trees along the path")
+- Start a project or set up drawings (e.g. "new project from the metric template", "create sheets A101-A105")
+- Fill sheets (e.g. "make a plan of each level and put it on its sheet", "schedule the planting")
+- Draw details (e.g. "a drafting view of the paving build-up, with the layers labelled")
+- Tidy a drawing set (e.g. "set every plan to 1:100", "add a Phase parameter to the sheets and stamp L.02 on them")
+- Open, save or close a model (e.g. "open C:\\Projects\\House.rvt", "save the model", "close without saving")
+
+## IMPORTANT
+
+- Run revit_status first if anything fails — it tells you whether Revit is even reachable.
+- If nothing is listening, the bridge add-in is probably not installed: run revit_install_bridge, then tell the user to restart Revit.
+- revit_query_elements caps at 500 rows. It always returns the total match count: if total is larger than what you got, say so instead of pretending the list is complete.
+- revit_get_elements returns only the parameters you name in params. Ask for what you need, not everything.
+- Every write tool is one undo step for the user. Do not split one logical change across several calls.
+- revit_new_project and revit_open_project are the tools that work with no document open; everything else needs a model.
+- The bridge answers Revit's modal dialogs and resolves its transaction warnings by itself, so an unattended run never stalls. Call revit_diagnostics after a batch of writes: a warning it resolved silently may mean the model did something you did not intend.
+- revit_close_project discards unsaved changes unless save is true. Call revit_save first when the work matters.
+- One project lives at one path and is rebuilt in place. When an attempt goes wrong, call revit_new_project again with the SAME save_path and overwrite: true — it closes that project in Revit, deletes the file and its backups, and builds it again. Never version a project into a new filename per iteration.
+- Call revit_list_titleblocks before revit_create_sheets: a sheet needs a title block, and an empty list means one has to be loaded in Revit first.
+- A sheet stays empty until something is on it: revit_place_views_on_sheets is what fills it, and it handles schedules as well as views.
+- A view lives on exactly one sheet. To show the same view twice, revit_duplicate_view first.
+- Revit's API cannot create the first legend in a document. revit_list_legends says what exists and revit_create_legend duplicates one; when there is none, ask the user to make one legend in the Revit UI (View tab > Legends > Legend) rather than passing off a drafting view as a legend.
+- Collapsible sheet groups ARE settable: revit_set_sheet_collections builds Revit's own sheet collections, so the grouping is in the model when it opens, with nothing to set up in the UI. It is a dry run until you pass dry_run: false, it reuses a collection of the same name rather than duplicating it, and it never renames or renumbers a sheet. revit_list_sheet_collections reads what exists. That is a different thing from the browser organisation scheme below, which groups by a PARAMETER and still cannot be applied from the API.
+- Grouping sheets into folders in the Project Browser is not settable from the API. revit_get_browser_organization shows the scheme in force, the scheme names the document has and the folders each sheet really sits in, and it reports canApplyFromApi false — that is the API's limit, not a bug to work around. Add the field with revit_create_project_parameter and stamp it with revit_set_sheet_parameters, then tell the user to point the browser organisation at that parameter once in the UI (right-click Sheets > Browser Organization). Stamping the parameter is NOT the grouping being applied; never report it as such.
+- Load real families before falling back to primitives. revit_load_families takes .rfa paths from Autodesk's library — C:\\ProgramData\\Autodesk\\RVT <year>\\Libraries\\<language>\\, under Planting\\, Site\\Accessories\\, Lighting\\Architectural\\External\\, Furniture\\, Doors\\, Windows\\ — and a library one release behind the running Revit still loads, because Revit upgrades it. That is the difference between a model made of real content and one made of spheres on sticks. Only when the library is genuinely not installed do revit_place_planting and revit_create_directshape become the answer; there are no MEP families either, so revit_create_pipes and revit_place_sprinklers model irrigation that way regardless.
+- revit_list_family_symbols is what the ids to place come from, and it filters by category, by family_name, or both. revit_place_families takes z as an absolute model elevation like everything else here and reports placedZ read back off each instance — check it rather than assuming.
+- Doors and windows are NOT revit_place_families: they have to cut the wall they sit in, and only revit_place_openings hosts them. Unhosted, a door stands in front of an uncut wall and the building stays a sealed box. It finds the nearest wall to each point for you and reports which one it used.
+- You can SEE the model: revit_create_3d_view (read modelExtents from it, then aim eye/target), revit_set_view_style with Realistic, then revit_export_view_image. Open the file reported under 'path', never the one you asked for — Revit renames it. This is not a photoreal render; the API cannot start Revit's raytracer. Cast shadows are revit_set_view_graphics, which probes whether the view's shadows parameter is writable and either writes it or posts Revit's own shadows command — read the method it reports rather than assuming it worked.
+- Three more calls are what stop an export reading as a screenshot of Revit: revit_set_view_background (a 3D view is drawn on flat dark slate until you give it a sky), revit_hide_view_categories with ['annotation'] (level datums and section marks float through an otherwise finished isometric), and revit_set_view_sun (the direction everything is lit from). Sun settings can be shared between views — check sharesSettings in the response.
+- Shadows and repeatable graphics: revit_get_view_graphics diagnoses what a view can actually take, revit_set_view_graphics sets style, detail, the lighting sliders and cast shadows, and revit_capture_view_template + revit_apply_view_template give a whole set of views the same graphics in one undo step. Be straight with the user about two things: a shadows write that reports method 'posted-command' is PENDING and unverified, not done; and a template captured from a view whose shadows were off turns shadows on nowhere.
+- A PNG is for looking at the model; a PDF is the deliverable. revit_export_view_image captures the view as Revit draws it on screen, so a dark view background comes out as a black-paper negative of the drawing and no setting makes that printable. revit_export_pdf is Revit's own exporter: vectors, white paper, real sheet size. Use it for anything anyone will read or plot, name the views and sheets explicitly, and trust the manifest's path/bytes — they are read off the disk, and a missing file is an error rather than a success.
+- A drawing that comes out tiny in the corner of its sheet is almost always an uncropped view: section marks and elevation markers sit far outside the building and the viewport is sized to all of it. The order that fixes it is revit_set_view_crop (model feet, dry run first), then revit_set_view_scale, then revit_get_sheet_layout to MEASURE where things landed, then revit_set_viewport_position (paper feet, centre of the box) if it still needs moving. Never guess a viewport coordinate — read the layout first. revit_hide_elements_in_view takes out what is merely in the way without deleting it, and revit_read_schedule is the only way to see what a schedule actually says. A PERSPECTIVE view breaks that order at one step: it has no view scale, so revit_set_view_scale refuses it with PERSPECTIVE_VIEW_HAS_NO_SCALE and revit_scale_perspective_crop re-sizes it instead — one multiplier, proportions locked, same shot, camera untouched. Reframing a perspective is still revit_set_view_crop; the two are not interchangeable.
+- A schedule on a sheet is not a viewport: it is anchored by its top-left corner, so it moves with revit_set_schedule_position (the instance id from revit_get_sheet_layout, not the schedule id), never with revit_set_viewport_position. A quantities schedule that lists every instance on its own row is not broken data — that is "Itemize every instance", and revit_configure_schedule with itemized false plus group_by is what collapses it to one row per type with a count. Check bodyRows before and after: that is the proof it worked.
+- The documentation write tools default dry_run TRUE, unlike everything else here. That is deliberate: they edit drawings a human has approved. Read the dry run's 'before', then call again with dry_run false. A crop refused with CROP_CONTROLLED_BY_TEMPLATE means the view's template owns it — say so and offer to change the template, rather than working around it.
+- Elements built that way schedule as one lump unless you say what they are. Put the species, the type or the zone in each entry's comments and mark — that is what makes a quantities schedule a breakdown.
+- Nothing has a material unless you give it one, and the whole model renders grey until you do. Materials go on at BUILD time for geometry (material_id on revit_create_directshape, revit_place_planting, revit_create_pipes, revit_place_sprinklers) because the solid carries it; walls and floors take theirs from their type, so make one with revit_create_wall_type / revit_create_floor_type first. revit_assign_material is only for elements that already exist and can take one — it reports the ones that cannot.
+- Changing how an EXISTING material looks in a render is revit_get_material_appearance then revit_set_material_appearance: read the appearance asset's real property names and types, then patch the ones you name. Never guess a property name — the asset's schema decides them — and never read a null appearanceAssetId as "it needs a texture": create_generic gives that material a textureless Generic asset to patch. The asset is copied before it is patched, so one material's new finish can never appear on another's surfaces.
+- Paving on graded terrain overlaps the surface unless you deal with it: revit_flatten_toposolid levels the region under it, and revit_create_floor takes an offset to lift the slab clear.
+- All lengths, coordinates and elevations are Revit internal units: decimal feet. Sheet coordinates are feet on the paper, not model feet.
+- Element ids are integers and only valid for the currently open document.
+`;
+
+export function createRevitServer(bridge = createBridge()) {
+  const server = new McpServer({ name: "revit", version: "1.0.0" }, { instructions });
+
+  registerReadTools(server, bridge);
+  registerWriteTools(server, bridge);
+  registerParameterTools(server, bridge);
+  registerModelTools(server, bridge);
+  registerGeometryTools(server, bridge);
+  registerMaterialTools(server, bridge);
+  registerMaterialAppearanceTools(server, bridge);
+  registerDocumentTools(server, bridge);
+  registerSheetTools(server, bridge);
+  registerSheetCollectionTools(server, bridge);
+  registerTitleblockTools(server, bridge);
+  registerViewTools(server, bridge);
+  registerGraphicsTools(server, bridge);
+  registerDetailTools(server, bridge);
+  registerDocumentationTools(server, bridge);
+  registerDiagnosticsTools(server, bridge);
+  registerQualityTools(server, bridge);
+  registerReloadTools(server, bridge);
+
+  // The install tools shell out to revit-bridge/install.ps1 and never touch the
+  // bridge, so they keep working when Revit is closed or the add-in is missing.
+  registerInstallTools(server);
+
+  return server;
+}
+
+async function main() {
+  const server = createRevitServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.stderr.write("Revit MCP server running on stdio\n");
+}
+
+// Only start the server when run as the entry point — the tests import
+// createRevitServer() and must not have stdio hijacked from under them.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+  });
+}