Skip to content

Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.

docs: render README diagrams to images, fix stale server metadata on upgrade

sammohammad5780a8f17250dff
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b10a66..be2187f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,9 @@
## Unreleased
+- Docs: the README diagrams are now images (light and dark, absolute URLs) so they show on directory sites that mirror the README but do not run Mermaid. The Mermaid sources live in `docs/diagrams/` and `scripts/render_diagrams.py` regenerates the PNGs.
+- Fix upgrade: `install.ps1` now removes the previous server package before copying the bundled Python, so old `aec_model_bridge-<version>.dist-info` folders no longer make the installed server report an old version.
+
## 1.3.2 - 2026-10-09
- Release: the MCP Registry publish now starts automatically after each stable release and reads the version from `VERSION`, so the bundle hash is no longer left stale.
diff --git a/README.md b/README.md
index 9f4c76f..cb605d4 100644
--- a/README.md
+++ b/README.md
@@ -119,88 +119,14 @@ The MCP client talks to one Python hub. The hub sends each call to the
provider that owns the tool. Providers for desktop apps talk to a small add-in
inside that app over localhost.
-```mermaid
----
-config:
- look: neo
- theme: base
- themeVariables:
- primaryColor: "#334155"
- primaryTextColor: "#FFFFFF"
- primaryBorderColor: "#1E293B"
- secondaryColor: "#334155"
- tertiaryColor: "#334155"
- lineColor: "#6E7781"
- textColor: "#6E7781"
- titleColor: "#6E7781"
- nodeTextColor: "#FFFFFF"
- clusterBkg: "rgba(110,119,129,0.10)"
- clusterBorder: "#6E7781"
- edgeLabelBackground: "#334155"
- actorBkg: "#334155"
- actorTextColor: "#FFFFFF"
- actorBorder: "#1E293B"
- actorLineColor: "#6E7781"
- signalColor: "#6E7781"
- signalTextColor: "#6E7781"
- labelBoxBkgColor: "#334155"
- labelBoxBorderColor: "#6E7781"
- labelTextColor: "#FFFFFF"
- loopTextColor: "#6E7781"
- sequenceNumberColor: "#FFFFFF"
- noteBkgColor: "#F59E0B"
- noteTextColor: "#1F1300"
- noteBorderColor: "#92400E"
- transitionColor: "#6E7781"
- transitionLabelColor: "#FFFFFF"
- stateLabelColor: "#FFFFFF"
- stateBkg: "#334155"
- labelBackgroundColor: "#334155"
- compositeBackground: "#334155"
- specialStateColor: "#6E7781"
----
-flowchart LR
- subgraph clients["AI clients"]
- client(["MCP client<br/>Claude, Codex, VS Code"])
- end
-
- subgraph hubzone["Python hub"]
- hub["MCP hub<br/>routes every tool call"]
- revitP["Revit provider"]
- rhinoP["Rhino provider"]
- navP["Navisworks provider"]
- ifcP["IFC provider"]
- speckleP["Speckle provider"]
- end
-
- subgraph apps["Desktop apps, add-ins on localhost"]
- revitA["Revit add-in"]
- rhinoA["Rhino add-in"]
- navA["Navisworks<br/>add-in<br/>in progress"]
- end
-
- ifcLib[("IFC files<br/>read with IfcOpenShell")]
- cloud(["Speckle server"])
-
- client -->|"sends tool calls"| hub
- hub -->|"routes Revit tools"| revitP
- hub -->|"routes Rhino tools"| rhinoP
- hub -.->|"routes Navisworks tools"| navP
- hub -->|"routes IFC tools"| ifcP
- hub -->|"routes Speckle tools"| speckleP
- revitP -->|"HTTP"| revitA
- rhinoP -->|"HTTP"| rhinoA
- navP -.->|"local bridge"| navA
- ifcP -->|"parses"| ifcLib
- speckleP -->|"syncs"| cloud
-
- classDef live fill:#0F766E,stroke:#0B4F4A,stroke-width:1.5px,color:#FFFFFF
- classDef wip fill:#F59E0B,stroke:#92400E,stroke-width:1.5px,stroke-dasharray:4 3,color:#1F1300
- classDef data fill:#4F46E5,stroke:#3730A3,stroke-width:1.5px,color:#FFFFFF
- class hub,revitP,rhinoP,ifcP,speckleP,revitA,rhinoA live
- class navP,navA wip
- class ifcLib,cloud data
-```
+<p align="center">
+ <picture>
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Sam-AEC/aec-model-bridge/main/docs/images/architecture-dark.png">
+ <img src="https://raw.githubusercontent.com/Sam-AEC/aec-model-bridge/main/docs/images/architecture-light.png" alt="Architecture of AEC Model Bridge: an MCP client such as Claude or Codex calls the Python MCP hub, which routes tool calls to the Revit, Rhino, Navisworks, IFC and Speckle providers. The Revit and Rhino providers talk to add-ins over localhost HTTP, the IFC provider reads IFC files with IfcOpenShell, and Navisworks is still in progress." width="900">
+ </picture>
+</p>
+
+<sub>Diagram source: [architecture.mmd](docs/diagrams/architecture.mmd). Regenerate the images with `python scripts/render_diagrams.py`.</sub>
Teal boxes work today. The amber dashed boxes are in progress. Indigo
shapes are data and external services.
@@ -212,73 +138,14 @@ approved plan. The default mode is `required`. The AI proposes a plan, you
review it in the Revit side panel, and the add-in runs it on Revit's main
thread in a named transaction.
-```mermaid
----
-config:
- look: neo
- theme: base
- themeVariables:
- primaryColor: "#334155"
- primaryTextColor: "#FFFFFF"
- primaryBorderColor: "#1E293B"
- secondaryColor: "#334155"
- tertiaryColor: "#334155"
- lineColor: "#6E7781"
- textColor: "#6E7781"
- titleColor: "#6E7781"
- nodeTextColor: "#FFFFFF"
- clusterBkg: "rgba(110,119,129,0.10)"
- clusterBorder: "#6E7781"
- edgeLabelBackground: "#334155"
- actorBkg: "#334155"
- actorTextColor: "#FFFFFF"
- actorBorder: "#1E293B"
- actorLineColor: "#6E7781"
- signalColor: "#6E7781"
- signalTextColor: "#6E7781"
- labelBoxBkgColor: "#334155"
- labelBoxBorderColor: "#6E7781"
- labelTextColor: "#FFFFFF"
- loopTextColor: "#6E7781"
- sequenceNumberColor: "#FFFFFF"
- noteBkgColor: "#F59E0B"
- noteTextColor: "#1F1300"
- noteBorderColor: "#92400E"
- transitionColor: "#6E7781"
- transitionLabelColor: "#FFFFFF"
- stateLabelColor: "#FFFFFF"
- stateBkg: "#334155"
- labelBackgroundColor: "#334155"
- compositeBackground: "#334155"
- specialStateColor: "#6E7781"
----
-sequenceDiagram
- autonumber
- participant You
- participant AI as AI assistant
- participant Hub as MCP hub + ApprovalGate
- participant Panel as Side panel (WebView2)
- participant Addin as Revit add-in
- participant Model as Revit model
-
- AI->>Hub: plan_actions (proposed changes)
- Hub->>Panel: show the pending plan
- Panel->>You: review the plan
- alt You approve
- You->>Panel: Approve
- Panel->>Hub: approved
- AI->>Hub: execute_plan
- Hub->>Addin: forward the commands
- Addin->>Model: run in one named transaction
- Model-->>Addin: done
- Addin-->>AI: result (rollback_plan can reverse it)
- else You reject, or never approve
- You->>Panel: Reject
- Panel->>Hub: rejected
- AI->>Hub: execute_plan
- Hub--xAI: blocked, the model is untouched
- end
-```
+<p align="center">
+ <picture>
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Sam-AEC/aec-model-bridge/main/docs/images/approval-flow-dark.png">
+ <img src="https://raw.githubusercontent.com/Sam-AEC/aec-model-bridge/main/docs/images/approval-flow-light.png" alt="Approval flow: the AI assistant proposes a plan, the MCP hub and ApprovalGate show it in the Revit side panel, and only after you approve does execute_plan forward the commands to the Revit add-in, which runs them in one named transaction. If you reject or never approve, the call is blocked and the model stays untouched." width="900">
+ </picture>
+</p>
+
+<sub>Diagram source: [approval-flow.mmd](docs/diagrams/approval-flow.mmd). Regenerate the images with `python scripts/render_diagrams.py`.</sub>
If a plan is approved and later turns out wrong, `rollback_plan` reverses it.
Rollback uses Revit Undo in the same session or inverse parameter values.
diff --git a/docs/diagrams/approval-flow.mmd b/docs/diagrams/approval-flow.mmd
new file mode 100644
index 0000000..ddba238
--- /dev/null
+++ b/docs/diagrams/approval-flow.mmd
@@ -0,0 +1,65 @@
+---
+config:
+ look: neo
+ theme: base
+ themeVariables:
+ primaryColor: "#334155"
+ primaryTextColor: "#FFFFFF"
+ primaryBorderColor: "#1E293B"
+ secondaryColor: "#334155"
+ tertiaryColor: "#334155"
+ lineColor: "#6E7781"
+ textColor: "#6E7781"
+ titleColor: "#6E7781"
+ nodeTextColor: "#FFFFFF"
+ clusterBkg: "rgba(110,119,129,0.10)"
+ clusterBorder: "#6E7781"
+ edgeLabelBackground: "#334155"
+ actorBkg: "#334155"
+ actorTextColor: "#FFFFFF"
+ actorBorder: "#1E293B"
+ actorLineColor: "#6E7781"
+ signalColor: "#6E7781"
+ signalTextColor: "#6E7781"
+ labelBoxBkgColor: "#334155"
+ labelBoxBorderColor: "#6E7781"
+ labelTextColor: "#FFFFFF"
+ loopTextColor: "#6E7781"
+ sequenceNumberColor: "#FFFFFF"
+ noteBkgColor: "#F59E0B"
+ noteTextColor: "#1F1300"
+ noteBorderColor: "#92400E"
+ transitionColor: "#6E7781"
+ transitionLabelColor: "#FFFFFF"
+ stateLabelColor: "#FFFFFF"
+ stateBkg: "#334155"
+ labelBackgroundColor: "#334155"
+ compositeBackground: "#334155"
+ specialStateColor: "#6E7781"
+---
+sequenceDiagram
+ autonumber
+ participant You
+ participant AI as AI assistant
+ participant Hub as MCP hub + ApprovalGate
+ participant Panel as Side panel (WebView2)
+ participant Addin as Revit add-in
+ participant Model as Revit model
+
+ AI->>Hub: plan_actions (proposed changes)
+ Hub->>Panel: show the pending plan
+ Panel->>You: review the plan
+ alt You approve
+ You->>Panel: Approve
+ Panel->>Hub: approved
+ AI->>Hub: execute_plan
+ Hub->>Addin: forward the commands
+ Addin->>Model: run in one named transaction
+ Model-->>Addin: done
+ Addin-->>AI: result (rollback_plan can reverse it)
+ else You reject, or never approve
+ You->>Panel: Reject
+ Panel->>Hub: rejected
+ AI->>Hub: execute_plan
+ Hub--xAI: blocked, the model is untouched
+ end
diff --git a/docs/diagrams/architecture.mmd b/docs/diagrams/architecture.mmd
new file mode 100644
index 0000000..4cc9b09
--- /dev/null
+++ b/docs/diagrams/architecture.mmd
@@ -0,0 +1,80 @@
+---
+config:
+ look: neo
+ theme: base
+ themeVariables:
+ primaryColor: "#334155"
+ primaryTextColor: "#FFFFFF"
+ primaryBorderColor: "#1E293B"
+ secondaryColor: "#334155"
+ tertiaryColor: "#334155"
+ lineColor: "#6E7781"
+ textColor: "#6E7781"
+ titleColor: "#6E7781"
+ nodeTextColor: "#FFFFFF"
+ clusterBkg: "rgba(110,119,129,0.10)"
+ clusterBorder: "#6E7781"
+ edgeLabelBackground: "#334155"
+ actorBkg: "#334155"
+ actorTextColor: "#FFFFFF"
+ actorBorder: "#1E293B"
+ actorLineColor: "#6E7781"
+ signalColor: "#6E7781"
+ signalTextColor: "#6E7781"
+ labelBoxBkgColor: "#334155"
+ labelBoxBorderColor: "#6E7781"
+ labelTextColor: "#FFFFFF"
+ loopTextColor: "#6E7781"
+ sequenceNumberColor: "#FFFFFF"
+ noteBkgColor: "#F59E0B"
+ noteTextColor: "#1F1300"
+ noteBorderColor: "#92400E"
+ transitionColor: "#6E7781"
+ transitionLabelColor: "#FFFFFF"
+ stateLabelColor: "#FFFFFF"
+ stateBkg: "#334155"
+ labelBackgroundColor: "#334155"
+ compositeBackground: "#334155"
+ specialStateColor: "#6E7781"
+---
+flowchart LR
+ subgraph clients["AI clients"]
+ client(["MCP client<br/>Claude, Codex, VS Code"])
+ end
+
+ subgraph hubzone["Python hub"]
+ hub["MCP hub<br/>routes every tool call"]
+ revitP["Revit provider"]
+ rhinoP["Rhino provider"]
+ navP["Navisworks provider"]
+ ifcP["IFC provider"]
+ speckleP["Speckle provider"]
+ end
+
+ subgraph apps["Add-ins on localhost"]
+ revitA["Revit add-in"]
+ rhinoA["Rhino add-in"]
+ navA["Navisworks<br/>add-in<br/>in progress"]
+ end
+
+ ifcLib[("IFC files<br/>read with IfcOpenShell")]
+ cloud(["Speckle server"])
+
+ client -->|"sends tool calls"| hub
+ hub -->|"routes Revit tools"| revitP
+ hub -->|"routes Rhino tools"| rhinoP
+ hub -.->|"routes Navisworks tools"| navP
+ hub -->|"routes IFC tools"| ifcP
+ hub -->|"routes Speckle tools"| speckleP
+ revitP -->|"HTTP"| revitA
+ rhinoP -->|"HTTP"| rhinoA
+ navP -.->|"local bridge"| navA
+ ifcP -->|"parses"| ifcLib
+ speckleP -->|"syncs"| cloud
+
+ classDef live fill:#0F766E,stroke:#0B4F4A,stroke-width:1.5px,color:#FFFFFF
+ classDef wip fill:#F59E0B,stroke:#92400E,stroke-width:1.5px,stroke-dasharray:4 3,color:#1F1300
+ classDef data fill:#4F46E5,stroke:#3730A3,stroke-width:1.5px,color:#FFFFFF
+ class hub,revitP,rhinoP,ifcP,speckleP,revitA,rhinoA live
+ class navP,navA wip
+ class ifcLib,cloud data
diff --git a/docs/images/approval-flow-dark.png b/docs/images/approval-flow-dark.png
new file mode 100644
index 0000000..d19af7e
Binary files /dev/null and b/docs/images/approval-flow-dark.png differ
diff --git a/docs/images/approval-flow-light.png b/docs/images/approval-flow-light.png
new file mode 100644
index 0000000..95f89c5
Binary files /dev/null and b/docs/images/approval-flow-light.png differ
diff --git a/docs/images/architecture-dark.png b/docs/images/architecture-dark.png
new file mode 100644
index 0000000..3a57cd8
Binary files /dev/null and b/docs/images/architecture-dark.png differ
diff --git a/docs/images/architecture-light.png b/docs/images/architecture-light.png
new file mode 100644
index 0000000..08766f8
Binary files /dev/null and b/docs/images/architecture-light.png differ
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index a8d9400..8da03f9 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -163,6 +163,23 @@ $targetPython = "C:\ProgramData\AECModelBridge\python"
if (Test-Path $sourcePython) {
Write-Host "`nInstalling bundled Python runtime..." -ForegroundColor Yellow
New-Item -ItemType Directory -Path $targetPython -Force | Out-Null
+
+ # Drop the previous server package first. Copying over the top left old
+ # aec_model_bridge-<version>.dist-info folders behind, and Python then reports
+ # the oldest one as the installed version.
+ $targetSite = Join-Path $targetPython "Lib\site-packages"
+ if (Test-Path -LiteralPath $targetSite) {
+ try {
+ Get-ChildItem -LiteralPath $targetSite -Directory -Filter "aec_model_bridge-*.dist-info" |
+ ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force }
+ $oldServer = Join-Path $targetSite "revit_mcp_server"
+ if (Test-Path -LiteralPath $oldServer) { Remove-Item -LiteralPath $oldServer -Recurse -Force }
+ }
+ catch {
+ Write-Warning "Could not remove the previous server package (is an MCP client running it?): $($_.Exception.Message)"
+ }
+ }
+
Copy-Item "$sourcePython\*" $targetPython -Recurse -Force
Write-Host " Installed to: $targetPython" -ForegroundColor Green
}
diff --git a/scripts/render_diagrams.py b/scripts/render_diagrams.py
new file mode 100644
index 0000000..bfcc385
--- /dev/null
+++ b/scripts/render_diagrams.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Render docs/diagrams/*.mmd to PNG images in docs/images/ (light and dark).
+
+Directory sites that mirror the README do not run Mermaid, so the README shows
+these images instead of code blocks. The .mmd files stay the source of truth.
+
+Needs Microsoft Edge (or Chrome) and Python 3.9+. The Mermaid library is
+downloaded once, pinned, into a temp folder.
+
+ python scripts/render_diagrams.py
+ python scripts/render_diagrams.py --browser "C:/Path/to/msedge.exe"
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / "docs" / "diagrams"
+OUT = ROOT / "docs" / "images"
+MERMAID_URL = "https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"
+BACKGROUNDS = {"light": "#ffffff", "dark": "#0d1117"}
+PAD = 24
+PROFILE = tempfile.mkdtemp(prefix="render-diagrams-profile-")
+
+BROWSERS = [
+ r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+ r"C:\Program Files\Microsoft\Edge\Application\msedge.exe",
+ r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+ "msedge", "chrome", "google-chrome", "chromium",
+]
+
+PAGE = """<!doctype html><meta charset="utf-8"><body style="margin:0;background:{bg}">
+<div id="wrap" style="display:inline-block;padding:{pad}px"><div id="g"></div></div><pre id="dim" style="display:none"></pre>
+<script src="mermaid.min.js"></script><script>
+(async function () {{
+ mermaid.initialize({{ startOnLoad: false }});
+ var out = await mermaid.render('d', {src});
+ document.getElementById('g').innerHTML = out.svg;
+ var svg = document.querySelector('#g svg');
+ var vb = svg.viewBox.baseVal;
+ svg.removeAttribute('style');
+ svg.setAttribute('width', vb.width);
+ svg.setAttribute('height', vb.height);
+ var r = document.getElementById('wrap').getBoundingClientRect();
+ document.getElementById('dim').textContent = 'DIM ' + Math.ceil(r.width) + 'x' + Math.ceil(r.height);
+}})();
+</script></body>"""
+
+
+def find_browser(hint: str | None) -> str:
+ for cand in ([hint] if hint else BROWSERS):
+ found = shutil.which(cand) or (cand if Path(cand).exists() else None)
+ if found:
+ return found
+ sys.exit("No Edge or Chrome found. Pass --browser <path>.")
+
+
+def run(browser: str, args: list[str]) -> str:
+ """Run the browser and return what it printed to stdout.
+
+ Edge and Chrome are GUI-subsystem programs on Windows and do not write to a
+ pipe that Python captures directly, so go through PowerShell, which does.
+ """
+ full = [browser, "--headless", "--disable-gpu", "--no-first-run", "--hide-scrollbars",
+ f"--user-data-dir={PROFILE}"] + args
+ if sys.platform == "win32":
+ quoted = ", ".join("'" + a.replace("'", "''") + "'" for a in full[1:])
+ script = f"& '{full[0]}' @({quoted}) 2>$null | Out-String"
+ done = subprocess.run(["powershell", "-NoProfile", "-Command", script],
+ capture_output=True, timeout=180)
+ else:
+ done = subprocess.run(full, capture_output=True, timeout=180)
+ return done.stdout.decode("utf-8", errors="replace")
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--browser")
+ args = parser.parse_args()
+ browser = find_browser(args.browser)
+ OUT.mkdir(parents=True, exist_ok=True)
+ work = Path(tempfile.mkdtemp(prefix="diagrams-"))
+ lib = work / "mermaid.min.js"
+ urllib.request.urlretrieve(MERMAID_URL, lib)
+ for mmd in sorted(SRC.glob("*.mmd")):
+ source = mmd.read_text(encoding="utf-8")
+ for mode, bg in BACKGROUNDS.items():
+ page = work / f"{mmd.stem}-{mode}.html"
+ page.write_text(PAGE.format(bg=bg, pad=PAD, src=json.dumps(source)), encoding="utf-8")
+ url = page.as_uri()
+ dom = run(browser, ["--virtual-time-budget=30000", "--dump-dom", url])
+ m = re.search(r"DIM (\d+)x(\d+)", dom)
+ if not m:
+ sys.exit(f"Could not render {mmd.name} ({mode}); the Mermaid source may be invalid.")
+ width, height = int(m.group(1)), int(m.group(2))
+ target = OUT / f"{mmd.stem}-{mode}.png"
+ run(browser, ["--virtual-time-budget=30000", "--force-device-scale-factor=2",
+ f"--window-size={width},{height}", f"--screenshot={target}", url])
+ print(f"{target.relative_to(ROOT)} {width}x{height} @2x")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())