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: plain-language edit pass and factual fixes against the code (#90)

A. Sam Mohammad1cd9fd2c4221
diff --git a/docs/compatibility.md b/docs/compatibility.md
index 8f9e0f4..aebcb85 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -2,7 +2,7 @@
AEC Model Bridge is a standard MCP server. It speaks the Model Context Protocol over stdio, so any AI client that can start a local MCP server can use it with the Revit model you have open.
-This page separates what is documented and set up in this repository from what should work because it is standard MCP. Nothing marked "not tested" has been tried by the maintainers.
+This page separates two groups. The first is what this repository documents and sets up. The second is what should work because it is standard MCP. The maintainers have not tried anything marked "not tested".
## AI assistants and MCP clients
@@ -22,9 +22,9 @@ Any framework with an MCP stdio client can launch the server and call its tools.
## What will not work directly
-A client that only accepts a remote MCP server over HTTP cannot start a local stdio server. That includes many browser-based chat apps. A local proxy that exposes a stdio server over HTTP can bridge the gap, but you would be opening the model to whatever can reach that proxy, so read [Security](security.md) first. The server is designed for a single machine, with the Revit add-in on loopback.
+A client that accepts only a remote MCP server over HTTP cannot start a local stdio server. Many browser-based chat apps work this way. A local proxy can expose a stdio server over HTTP. That opens your model to anything that can reach the proxy, so read [Security](security.md) first. The server is designed for a single machine, with the Revit add-in on loopback.
-The Revit add-in is always required for live work. The server talks to a running copy of Revit on Windows.
+Live work always needs the Revit add-in. The server talks to a running copy of Revit on Windows.
## Applications and formats
@@ -44,4 +44,4 @@ Registry files for the official MCP Registry (`server.json`), Smithery (`smither
## Try it without Revit
-Set `MCP_REVIT_MODE` to `mock` and any client above can browse the tools and get sample answers. Mock data is never used in live mode.
+Set `MCP_REVIT_MODE` to `mock`. Any client above can then browse the tools and get sample answers. Live mode does not use mock data.
diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md
index 3c45e70..c7e0bd4 100644
--- a/docs/configuration-reference.md
+++ b/docs/configuration-reference.md
@@ -1,40 +1,43 @@
-# Configuration Reference
+# Configuration reference
-This page documents the main environment variables, package metadata, and runtime settings used by the Revit MCP bridge.
+This page lists the environment variables, package files and runtime modes of the Revit MCP server.
-## Runtime Modes
+## Runtime modes
-The server supports two runtime modes:
+The server has two modes. Set the mode with `MCP_REVIT_MODE`.
-- `mock`: uses the built-in mock bridge for CI, development, and tests.
-- `bridge`: connects to a live Revit add-in over its local registry entry or an explicit bridge URL.
+- `mock`: uses built-in sample data. Use it for tests, development and trying the tools without Revit. This is the default.
+- `bridge`: connects to a running Revit add-in. The server finds the add-in through its local registry entry, or through an explicit bridge URL.
-## Environment Variables
+## Environment variables
| Variable | Required | Default | Description |
|---|---:|---|---|
-| `MCP_REVIT_MODE` | Yes | `mock` | Selects the active bridge mode. |
-| `MCP_REVIT_BRIDGE_URL` | No | auto-discovered | Explicit URL of the Revit bridge listener. Overrides registry discovery. |
-| `MCP_REVIT_HOST_VERSION` | No | newest live Revit | Revit year to select from the local registry, such as `2024` or `2026`. |
-| `MCP_REVIT_ALLOWED_DIRECTORIES` | No | the workspace directory | Semicolon-separated directories the server may access. Path-traversal protection applies to exactly this list. An explicit value always wins. |
-| `MCP_REVIT_WORKSPACE_DIR` | No | `~/Documents/AEC Model Bridge` | Root directory for generated files and workspace-backed tools. The default folder is created the first time the server needs it (never at import), so a one-click install works with no configuration. |
-| `MCP_REVIT_AUDIT_LOG` | No | `workspace/audit.jsonl` | Audit log path used by the security layer. |
-| `MCP_REVIT_ANTHROPIC_API_KEY` | No | unset | Anthropic API key for the panel's native Claude chat (`agent_native.py`, ADR 0012). If you don't set it, "Claude" chat falls back to the `claude` CLI when that's on PATH. Otherwise no AI provider is available. You can also put it in a `.env` file. The hub reads it only at startup, so restart Revit after you set or change it. The panel's Settings view can't set it. |
+| `MCP_REVIT_MODE` | No | `mock` | Selects `mock` or `bridge`. Set `bridge` for live Revit. |
+| `MCP_REVIT_BRIDGE_URL` | No | auto-discovered | Explicit URL of the Revit bridge. Overrides registry discovery. |
+| `MCP_REVIT_HOST_VERSION` | No | newest live Revit | Revit year to pick from the local registry, such as `2024` or `2026`. |
+| `MCP_REVIT_ALLOWED_DIRECTORIES` | No | the workspace directory | Directories the server may read and write, separated by semicolons. The path guard checks against exactly this list. A value you set always wins. |
+| `MCP_REVIT_WORKSPACE_DIR` | No | `~/Documents/AEC Model Bridge` | Root folder for generated files and workspace-backed tools. The server creates the default folder the first time it needs it, so a one-click install works with no configuration. |
+| `MCP_REVIT_AUDIT_LOG` | No | `audit.log` | Path of the audit log. A relative path resolves against the working directory of the server process. See [Logging and audit](logging-and-audit.md). |
+| `MCP_REVIT_LOG_LEVEL` | No | `INFO` | Log level of the server. |
+| `MCP_REVIT_APPROVAL_MODE` | No | `required` | With `required`, a tool that changes the model needs a `plan_id` for an approved plan. Any other value turns this check off. Leave it at `required`. |
+| `MCP_REVIT_ENABLE_USER_MODULES` | No | `false` | Set to `true` to load modules from `%LOCALAPPDATA%\AECModelBridge\modules`. See [Module authoring](module-authoring.md). |
+| `MCP_REVIT_ALLOW_PYTHON_HOST` | No | `false` | Set to `true` to allow tools that run raw Python on the host, such as `revit_execute_python`. Leave it off unless you need it. |
+| `MCP_REVIT_ANTHROPIC_API_KEY` | No | unset | Anthropic API key for the panel's built-in Claude chat (`agent_native.py`, ADR 0012). If you do not set it, the Claude chat falls back to the `claude` command-line tool when that is on your PATH. If neither is available, no AI provider is available. You can also put the key in a `.env` file. The hub reads it only at startup, so restart Revit after you set or change it. The panel's Settings view cannot set it. |
+| `MCP_REVIT_LEGACY_PORT` | No | unset | Read by the Revit add-in, not the Python server. Set to `true` or `1` to bind the add-in to fixed port `3000` with no authentication. See [Security](security.md). |
| `REVIT_SDK` | Build only | unset | Optional path used by the add-in build scripts. |
-## Package and Registry Metadata
+## Package and registry files
-The Python package and MCP registry metadata are defined in:
+These files define the Python package and the MCP registry entry:
- `packages/mcp-server-revit/pyproject.toml`
- `packages/mcp-server-revit/manifest.json`
- `server.json`
-The current package name is `aec-model-bridge`, and the official repository URL is:
+The package name is `aec-model-bridge`. The official repository is https://github.com/Sam-AEC/aec-model-bridge.
-- https://github.com/Sam-AEC/aec-model-bridge
-
-## MCP Client Example
+## MCP client example
```json
{
@@ -55,6 +58,6 @@ The current package name is `aec-model-bridge`, and the official repository URL
## Notes
-- The server should be run from the repository root or an environment where the package is installed in editable mode.
-- For Revit integration, make sure the Revit add-in is installed and the requested Revit version is running before testing.
-- Configure separate MCP client entries with different `MCP_REVIT_HOST_VERSION` values to target multiple open Revit versions side by side.
+- Run the server from the repository root, or from an environment where you installed the package in editable mode.
+- For live Revit, install the add-in and start the Revit version you want before you test.
+- To use several open Revit versions side by side, add one MCP client entry for each version. Give each entry its own `MCP_REVIT_HOST_VERSION`.
diff --git a/docs/install-buttons.md b/docs/install-buttons.md
index 97fafd5..21a34ea 100644
--- a/docs/install-buttons.md
+++ b/docs/install-buttons.md
@@ -1,7 +1,7 @@
# Install buttons
-How the one-click install links in the README are built. Regenerate every
-link with:
+This page explains how the one-click install links in the README are built. To
+regenerate every link, run:
```text
python scripts/make_install_links.py # print them
@@ -68,8 +68,9 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=aec-model-bridge&config=eyJj
The README badge uses the https form that other MCP projects use because
GitHub strips `cursor:` links:
`https://cursor.com/en/install-mcp?name=<name>&config=<same base64>`. That
-https form is not in the Cursor docs I could reach and was not reachable from
-the machine used to build it, so check the button once in a browser.
+https form is UNVERIFIED. It is not in the Cursor docs, and it could not be
+reached from the machine used to build it. Open the button once in a browser
+to check it.
## Claude Desktop
diff --git a/docs/install.md b/docs/install.md
index 915b4f5..3642445 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -5,9 +5,9 @@ AEC Model Bridge has two parts:
1. A Python MCP server that your AI client starts.
2. A native add-in that Revit loads.
-You need both for live Revit automation. Mock mode needs only the Python
-server. Supported Revit versions are 2024 to 2027. For release numbering, see
-[versioning](versioning.md).
+You need both to work with a live Revit model. Mock mode needs only the Python
+server. It uses sample data. Supported Revit versions are 2024 to 2027. For
+release numbering, see [versioning](versioning.md).
## Requirements
@@ -27,25 +27,27 @@ General requirements:
## Download the installer
-The easiest way to install on Windows. No Python, Git or build tools needed.
+This is the easiest way to install on Windows. You do not need Python, Git or build tools.
1. Open the [latest release](https://github.com/Sam-AEC/aec-model-bridge/releases/latest)
and download `AECModelBridge-Setup-<version>.exe`.
2. Close Revit, then double-click the file. Windows SmartScreen may warn that the
publisher is unknown, because the installer is not code-signed yet. Choose
- **More info**, then **Run anyway**. The checksum is in `SHA256SUMS.txt` on the
- same page.
-3. On the *Revit versions* page, the Revit years found on your computer are already
- ticked. Change them if you like. Optionally tick *Set up Claude Desktop and VS Code*;
- your current settings are copied to a `.aec-backup-<date>` file first.
+ **More info**, then **Run anyway**. To check the download, compare it with the
+ checksum in `SHA256SUMS.txt` on the same page.
+3. On the *Revit versions* page, the installer has already ticked the Revit years it
+ found on your computer. Change them if you like. You can also tick *Set up Claude
+ Desktop and VS Code*. The installer first copies your current settings to a
+ `.aec-backup-<date>` file.
4. Start Revit and look for the **AEC Bridge** tab.
The installer needs no administrator rights. It puts the add-in in
`C:\ProgramData\AECModelBridge\bin\<year>`, the bundled Python and MCP server in
`C:\ProgramData\AECModelBridge\python`, and a per-user manifest in
-`%APPDATA%\Autodesk\Revit\Addins\<year>`. Installing again upgrades in place.
-To remove everything, use *Apps > Installed apps > AEC Model Bridge > Uninstall*.
-Close Revit first; both Setup and the uninstaller stop if Revit is running.
+`%APPDATA%\Autodesk\Revit\Addins\<year>`. Running the installer again upgrades the
+existing install.
+To remove everything, open *Apps > Installed apps > AEC Model Bridge > Uninstall*.
+Close Revit first. Both Setup and the uninstaller stop if Revit is running.
For a silent install (IT deployment):
@@ -53,9 +55,9 @@ For a silent install (IT deployment):
.\AECModelBridge-Setup-<version>.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /COMPONENTS="y2025,y2026"
```
-`/COMPONENTS` takes `y2024`, `y2025`, `y2026`, `y2027`; leave it out to use the
-detected Revit versions. Add `/TASKS="mcpclients"` to set up Claude Desktop and VS Code,
-and `/LOG="setup.log"` to keep a log. To build the installer yourself, see
+`/COMPONENTS` takes `y2024`, `y2025`, `y2026` and `y2027`. Leave it out to use the
+Revit versions the installer detects. Add `/TASKS="mcpclients"` to set up Claude Desktop
+and VS Code. Add `/LOG="setup.log"` to keep a log. To build the installer yourself, see
[build and install scripts](build-and-install-scripts.md).
## Install From Source
@@ -71,13 +73,13 @@ py -m venv .venv
python -m pip install -e packages/mcp-server-revit
```
-Choose the Revit version installed on your machine:
+Enter the Revit year installed on your machine:
```powershell
$RevitVersion = Read-Host "Revit year (2024, 2025, 2026, or 2027)"
```
-Build, package, and install the matching add-in. To only build, run
+Build, package and install the add-in for that year. To only build, run
`.\scripts\build-addin.ps1 -RevitVersion 2026` (use your Revit year):
```powershell
@@ -85,7 +87,7 @@ Build, package, and install the matching add-in. To only build, run
.\scripts\install.ps1 -RevitVersion $RevitVersion
```
-The default installation is per user:
+The default install is per user. It uses these locations:
```text
Add-in manifest:
@@ -98,7 +100,7 @@ Configuration:
C:\ProgramData\AECModelBridge\config\default.json
```
-For an all-user manifest installation:
+To install the manifest for all users:
```powershell
.\scripts\install.ps1 -RevitVersion $RevitVersion -AllUsers
@@ -110,15 +112,14 @@ To package every supported Revit version:
.\scripts\package.ps1 -RevitVersion All
```
-You can then run `install.ps1` once for each installed Revit year.
+Then run `install.ps1` once for each Revit year you have installed.
## Install From a Release
Download a package matching your Revit version from
[GitHub Releases](https://github.com/Sam-AEC/aec-model-bridge/releases).
-Extract the archive, check the available folders under `bin`, and install the
-matching year:
+Extract the archive and list the folders under `bin`. Then install your year:
```powershell
Get-ChildItem .\bin -Directory
@@ -126,13 +127,13 @@ $RevitVersion = Read-Host "Choose one of the listed Revit years"
.\install.ps1 -RevitVersion $RevitVersion
```
-If a prebuilt package is not available for your year, use the source
-installation above.
+If there is no prebuilt package for your year, use the source install above.
-## Configure an MCP Client
+## Configure an MCP client
-The server requires an allowed workspace. In bridge mode it auto-discovers the
-newest open Revit instance; set `MCP_REVIT_HOST_VERSION` to target a specific
+If you do not set a workspace, the server uses `~/Documents/AEC Model Bridge`.
+The examples below set one explicitly. In bridge mode the server connects to the
+newest open Revit by default. Set `MCP_REVIT_HOST_VERSION` to pick a specific
Revit year:
```json
@@ -161,17 +162,17 @@ Revit year:
}
```
-The allowed directories value accepts multiple paths separated by semicolons.
+`MCP_REVIT_ALLOWED_DIRECTORIES` accepts several paths separated by semicolons.
-VS Code users can start from [`.vscode/mcp.json`](../.vscode/mcp.json).
+In VS Code, you can start from [`.vscode/mcp.json`](../.vscode/mcp.json).
-Clients with MCP Bundle support can install the `.mcpb` asset from the latest
-release. The Revit add-in must still be installed separately.
+If your client supports MCP Bundles, install the `.mcpb` file from the latest
+release. You still need to install the Revit add-in separately.
-## Verify the Bridge
+## Verify the bridge
-The add-in writes a live endpoint file under
-`%LOCALAPPDATA%\AECModelBridge\registry` when Revit starts:
+When Revit starts, the add-in writes an endpoint file under
+`%LOCALAPPDATA%\AECModelBridge\registry`. This command reads that file and calls the bridge:
```powershell
$registry = Get-ChildItem "$env:LOCALAPPDATA\AECModelBridge\registry\revit-*.json" | Select-Object -First 1
@@ -188,11 +189,11 @@ The response should include:
}
```
-The reported year will match the running Revit version.
+The reported year matches the Revit version that is running.
-## Mock Mode
+## Mock mode
-Mock mode runs the MCP server without Revit:
+Mock mode runs the MCP server without Revit. It returns sample data:
```powershell
$env:MCP_REVIT_MODE = "mock"
@@ -202,7 +203,7 @@ $env:MCP_REVIT_ALLOWED_DIRECTORIES = "C:\revit-workspace"
python -m revit_mcp_server
```
-Run the automated tests with:
+To run the automated tests:
```powershell
python -m pytest packages/mcp-server-revit/tests
@@ -216,7 +217,7 @@ python -m pytest packages/mcp-server-revit/tests
- Confirm the `AEC Bridge` ribbon tab is present. It has Connection, Workflows and Tools panels.
- Check that the manifest year matches the running Revit year.
- Check the bridge log at `%APPDATA%\AECModelBridge\Logs\bridge.jsonl`.
-- Confirm no other process is using port `3000`.
+- Only if you turned on legacy mode (`MCP_REVIT_LEGACY_PORT=1`): confirm no other program is using port `3000`. The default mode picks a free port by itself.
### Add-in build fails
@@ -224,14 +225,14 @@ python -m pytest packages/mcp-server-revit/tests
- For Revit 2024, install the .NET Framework 4.8 developer pack.
- Confirm the selected `-RevitVersion` is one of `2024`, `2025`, `2026`, or
`2027`.
-- If Revit is not installed on the build machine, the project uses matching
- Revit API reference packages for compilation.
+- If Revit is not installed on the build machine, the build uses the matching
+ Revit API reference packages.
### Workspace access denied
- Use absolute paths for `MCP_REVIT_WORKSPACE_DIR`.
-- Include every required directory in `MCP_REVIT_ALLOWED_DIRECTORIES`.
-- Separate multiple Windows paths with semicolons.
+- List every folder you need in `MCP_REVIT_ALLOWED_DIRECTORIES`.
+- Separate several Windows paths with semicolons.
-See the [configuration reference](configuration-reference.md) and
-[security guide](security.md) for advanced settings.
+For more settings, see the [configuration reference](configuration-reference.md)
+and the [security guide](security.md).
diff --git a/docs/logging-and-audit.md b/docs/logging-and-audit.md
index 30f4457..79545f8 100644
--- a/docs/logging-and-audit.md
+++ b/docs/logging-and-audit.md
@@ -1,64 +1,67 @@
-# Logging And Audit
+# Logging and audit
-This repository records operational information in two different layers:
+The project keeps two separate logs:
-- Python-side audit logging
-- C# bridge-side runtime logging
+- the Python-side audit log
+- the Revit add-in runtime log
-## Python Audit Recorder
+## Python audit log
-The audit implementation lives in [packages/mcp-server-revit/src/revit_mcp_server/security/audit.py](../packages/mcp-server-revit/src/revit_mcp_server/security/audit.py).
+The code is in [packages/mcp-server-revit/src/revit_mcp_server/security/audit.py](../packages/mcp-server-revit/src/revit_mcp_server/security/audit.py).
-`AuditRecorder.record()` writes one JSON line per tool invocation with:
+`AuditRecorder.record()` writes one JSON line per tool call. Each line holds:
-- UTC timestamp
-- tool name
-- request ID
-- payload
-- response
+- a UTC timestamp
+- the tool name
+- the request ID
+- the payload
+- the response
-This is the structured trail for MCP-level actions.
+Tokens, secrets and file paths are replaced before the line is written. See [Security](security.md). Set the file with `MCP_REVIT_AUDIT_LOG`. The default is `audit.log` in the working directory of the server process.
-## Bridge Runtime Logs
+This log shows what the MCP server asked for.
-The Revit add-in initializes Serilog in [App.cs](../packages/revit-bridge-addin/src/Bridge/App.cs).
+Note: in the current code, only the legacy server (`legacy/server.py`) creates an `AuditRecorder`. The main server (`mcp_server.py`) uses the same redaction but does not write this file. If `audit.log` is missing, this is the likely reason.
-Current behavior:
+## Add-in runtime log
-- log file path is created under `%APPDATA%\AECModelBridge\Logs\bridge.jsonl`
-- logs roll daily
-- bridge startup, shutdown, request receipt, and execution errors are recorded
+The Revit add-in starts Serilog in [App.cs](../packages/revit-bridge-addin/src/Bridge/App.cs).
-This is the operational trail for the .NET side of the system.
+- The log file is `%APPDATA%\AECModelBridge\Logs\bridge.jsonl`.
+- The log rolls over daily.
+- It records add-in startup, shutdown, incoming requests and execution errors.
-## Why Two Layers Exist
+The panel hub writes its own log, `panel-hub.log`, in the same folder.
-The Python process and the Revit add-in do not share a runtime or process boundary.
+This log shows what Revit received and ran.
-Because of that:
+## Why there are two logs
-- Python audit logs tell you what the MCP layer believed it asked for
-- bridge logs tell you what the Revit-hosted runtime actually received and executed
+The Python server and the Revit add-in run as separate processes. They do not share a runtime.
-When debugging production issues, both logs matter.
+- The Python audit log tells you what the MCP server believed it asked for.
+- The add-in log tells you what Revit actually received and ran.
-## What To Expect In Incidents
+When you investigate a problem, read both.
-If the MCP server validates and sends a request successfully, but Revit fails to execute it:
+## What to expect when something fails
-- Python audit may still look normal
-- bridge log will often hold the actionable failure
+If the server sends a request and Revit fails to run it:
-If a path is rejected or payload shape is wrong before the bridge is contacted:
+- The Python audit log may still look normal.
+- The add-in log usually holds the useful error.
-- Python audit and validation behavior will matter more than the bridge log
+If the server rejects a path, or the payload has the wrong shape, the request never reaches the add-in:
-## Operational Rule
+- Look at the Python audit log and the error the client showed.
+- The add-in log will have nothing for this request.
-Never treat one log as the whole story. For live bridge failures, correlate:
+## Rule of thumb
-1. Python audit entry
-2. bridge runtime log entry
-3. any client-visible error response
+Do not rely on one log alone. For a failed live request, compare these three records:
-That three-point check is the fastest way to separate schema problems, transport problems, and live Revit execution problems.
+1. the Python audit entry
+2. the add-in log entry
+3. the error the client showed
+
+This check quickly shows whether the problem is the input, the connection or Revit itself.
diff --git a/docs/module-authoring.md b/docs/module-authoring.md
index ccfc04f..512e5f6 100644
--- a/docs/module-authoring.md
+++ b/docs/module-authoring.md
@@ -1,13 +1,13 @@
-# Developer Guide: Module Authoring
+# Developer guide: module authoring
-Modules in AEC Model Bridge allow developers and firms to package commands, workflows, schemas, and QA rules.
+A module packages commands, workflows, schemas and QA rules. Developers and firms can add their own.
-## 1. Directory Structure
+## 1. Directory structure
-A module folder must reside either:
+A module folder goes in one of these places:
- **Built-in**: `packages/mcp-server-revit/src/revit_mcp_server/modules/<module_id>/`
-- **User/Firm Folder** (if `enable_user_modules` is `True`): `%LOCALAPPDATA%\AECModelBridge\modules\<module_id>\`
-- **Installed Package**: Declared as `aec_model_bridge.modules` entry points.
+- **User or firm folder**: `%LOCALAPPDATA%\AECModelBridge\modules\<module_id>\`. The server loads it only when `enable_user_modules` is `True`. Set this with the environment variable `MCP_REVIT_ENABLE_USER_MODULES`.
+- **Installed package**: the package declares an `aec_model_bridge.modules` entry point.
```
<module_id>/
@@ -17,7 +17,7 @@ A module folder must reside either:
└── ui/ # HTML panel components (optional)
```
-## 2. Manifest Schema (`module.json`)
+## 2. Manifest schema (`module.json`)
```json
{
@@ -56,15 +56,15 @@ A module folder must reside either:
## 3. Permissions
-Permissions declared in the manifest are verified at dispatch time:
-- `model.read`: Standard read tools.
-- `model.write`: Mutating tools (always checked against the ActionPlan approval gate).
-- `model.delete`: Destructive operations.
-- `workspace.write`: Restricted sandboxed files output.
-- `net.local` / `net.cloud`: Local connection vs cloud synchronizations.
-- `python.host`: Raw python escapes (e.g. `revit_execute_python`). Disabled unless `allow_python_host` is explicitly `True`.
+The server checks the permissions in the manifest each time a command runs:
+- `model.read`: standard read tools.
+- `model.write`: tools that change the model. The server always checks these against the action plan approval gate.
+- `model.delete`: destructive operations.
+- `workspace.write`: writing files inside the sandboxed workspace.
+- `net.local` and `net.cloud`: local connections and cloud sync.
+- `python.host`: raw Python on the host, such as `revit_execute_python`. It stays off unless `allow_python_host` is `True`. Set this with `MCP_REVIT_ALLOW_PYTHON_HOST`.
-## 4. Hook Evaluation
+## 4. Hooks
-- **`validate` hook**: Called before execution. Returns `{"ok": true}` or `{"blockers": ["Details"]}` to reject execution.
-- **`on_result` hook**: Called after execution asynchronously.
+- **`validate` hook**: runs before the command. Return `{"ok": true}` to continue. Return `{"blockers": ["Details"]}` to stop the command.
+- **`on_result` hook**: runs after the command, asynchronously.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index d65cdb4..31bf46d 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -1,19 +1,12 @@
-# Adoption priorities for BIM coordinators
+# Roadmap: adoption priorities for BIM coordinators
-Prepared 2026-10-09. These are proposed priorities, not shipped-feature or
-traction claims. The initial audience is BIM coordinators who need to find
-missing model data and approve parameter fixes.
+Prepared 2026-10-09. These are proposed priorities. They are not claims about shipped features or users. The first audience is BIM coordinators who need to find missing model data and approve parameter fixes.
-The first useful result is a repeatable **find missing parameters → review
-exact changes → approve → verify** workflow on a synthetic model in a real
-Revit session. Missing door Marks are the smallest first case; inconsistent
-values follow once coordinator rules and expected values are explicit. Existing
-QA rules, parameter planning and the approval gate provide the foundation.
-Effort labels below are relative estimates, not delivery dates.
+The first goal is a repeatable workflow on a synthetic model in a real Revit session: **find missing parameters → preview the exact changes → approve → verify**. Missing door Marks are the smallest first case. Inconsistent values come later, once coordinators set the rules and expected values. The existing QA rules, parameter planning and approval gate are the base. Effort labels are relative estimates, not delivery dates.
| Priority | Deliverable and rationale | Effort | Verification criteria |
| --- | --- | --- | --- |
-| 0 | Require explicit real snapshots in the live QA and parameter workflow, and fail clearly when one is absent. Today these modules generate mock data when `snapshot_id` is omitted, even if Revit is connected. Removing that ambiguity is a prerequisite for a credible demo and reliable model fixes. | Small to medium | The live path rejects absent snapshots with an actionable instruction, validates the snapshot document identity, and identifies its source/time in findings and previews. Explicit mock mode remains labelled. The after check uses a newly captured snapshot of the same document; synthetic snapshot data cannot be presented as a live result. |
+| 0 | Require a real snapshot in the live QA and parameter workflow, and fail with a clear message when none is given. **Partly done:** in bridge mode, the QA checker and parameter manager now reject an empty `snapshot_id` (`require_snapshot_or_mock`) instead of using generated mock data. Still open: check that the snapshot belongs to the open document, and show its source and time in findings and previews. | Small | The live path rejects a missing snapshot with a clear instruction (done). It also checks the snapshot's document identity and shows its source and time in findings and previews (open). Mock mode stays labelled. The after check uses a newly captured snapshot of the same document, so sample data cannot pass as a live result. |
| 1 | A short real Revit demo and repeatable runbook. Show missing door Marks, select affected elements, review proposed values, approve once and rerun the check. This makes the existing product understandable and provides evidence of a complete coordinator task. | Small, with live Revit access | Rebuild the fixture and obtain the same rule counts on two runs. Before the door fix, the intended baseline is 12 missing Marks and 3 missing room Numbers; after it, 0 missing Marks and 3 unchanged room findings. Capture actual counts, Revit version, commit and before/after evidence. A rejected plan must leave parameters unchanged. Publish a recording only after the live result is verified. |
| 2 | Make the parameter fix review dependable. Use explicit element IDs, parameter names, old/new values, warnings and skipped elements; use user-confirmed numbering rules. Coordinators need to know exactly which model data will change and why. | Medium | Only selected missing values change. Existing populated Marks remain intact. Read-only or owned elements surface actionable failures/skips. A fresh read checks final values and reruns QA; failed or partial execution cannot appear as a completed fix. Cover stale-document/changed-value handling and document the supported rollback path. |
| 3 | An install-to-first-check diagnostic path. Explain the Revit version, add-in connection, active document, hub/client state and next action in one place. The source/install instructions currently require several components, so reducing setup failures helps new users reach the demo. | Small to medium | A fresh Windows account installs one supported Revit package and completes the read-only check without source editing. Missing Python, wrong Revit package, stopped bridge and no open document each produce a specific recovery step. Test each advertised Revit version before claiming equivalent live support. |
@@ -21,14 +14,14 @@ Effort labels below are relative estimates, not delivery dates.
## First demo scope
-The snapshot contract needs repair first. The add-in used to write
-`snapshots/snapshot-{GUID}.json` while returning a bare GUID, and the Python
-modules load `snapshots/{snapshot_id}.json`; the add-in now writes
-`snapshots/{GUID}.json` (compile and verify against live Revit before relying
-on it). The add-in also uses its own workspace environment, which can differ
-from the Python server's workspace. Confirm the workspace matches, and verify the
-snapshot covers the categories required by the QA rules. Never silently replace
-a failed live extraction with generated mock data.
+Fix the snapshot contract first. The add-in used to write
+`snapshots/snapshot-{GUID}.json` but return a bare GUID. The Python modules load
+`snapshots/{snapshot_id}.json`. The add-in now writes `snapshots/{GUID}.json`.
+Compile it and test it against live Revit before you rely on it. The add-in also
+reads its own `MCP_REVIT_WORKSPACE_DIR`, which can differ from the Python
+server's workspace. Check that both use the same folder. Check that the snapshot
+covers the categories the QA rules need. Never replace a failed live extraction
+with generated mock data.
Use a disposable copy of the [canonical model](../fixtures/canonical-model/README.md).
The [seeded defect manifest](../fixtures/canonical-model/seeded-defects.json)
@@ -40,10 +33,11 @@ the approved change.
Capture a real snapshot from that open synthetic Revit document and pass its
explicit `snapshot_id` to every QA and parameter call. Record document identity
-and source/time. Capture a new snapshot after execution for verification. An
-omitted snapshot currently falls back to generated mock data in both modules;
-connected Revit alone does not establish that findings describe the open model.
-Complete priority 0 before treating the product's default workflow as live.
+and source/time. Capture a new snapshot after execution for verification. In
+mock mode, an omitted snapshot still falls back to generated mock data. In
+bridge mode it is now rejected. A connection to Revit alone does not show that
+findings describe the open model, so finish the open part of priority 0 before
+you treat the default workflow as live.
Record the check result, affected element selection, parameter preview, human
approval, execution result and a fresh check. Include a rejected-plan run and
@@ -69,12 +63,9 @@ demo; record missing coverage and verify the full sequence in the live client.
## Evidence and sequencing
- [Core QA rule pack](../packages/mcp-server-revit/src/revit_mcp_server/modules/qaqc_checker/rules/core.yaml) already contains `door_missing_mark` and `room_missing_number`; [the checker](../packages/mcp-server-revit/src/revit_mcp_server/modules/qaqc_checker/module.py) tracks findings in a workspace SQLite store.
-- The checker's `_get_data` and the [parameter manager's](../packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.py) `_get_elements` call `generate_mock_snapshot()` when `snapshot_id` is empty. This observed fallback motivates priority 0; it is a proposed fix, not a claim that it has been implemented.
+- The checker's `_get_data` and the [parameter manager's](../packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.py) `_get_elements` call `require_snapshot_or_mock()` when `snapshot_id` is empty. In bridge mode this raises an error. In mock mode they still call `generate_mock_snapshot()`. This covers the first part of priority 0. Document identity checks are not implemented.
- [Parameter manager](../packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.py) already produces planned changes with before values, validation errors and worksharing warnings. Validate those warnings against real Revit ownership before promising batch safety.
- [Approval lifecycle](0008-approval-gate-lifecycle.md) and [native chat trust model](0012-native-agent-chat-backend.md) describe the human approval boundary. Acceptance criteria must verify the concrete client path used in the demo.
- [Installation](install.md) documents the Python server and native add-in requirements; [audit logging](logging-and-audit.md) explains the two log layers needed to correlate a requested change with actual Revit execution.
-Complete the first demo before expanding the integration surface. Decide the
-next workflow from observed coordinator setup failures and repeated QA tasks.
-Keep Navisworks, Power BI and broader provider work behind this measured adoption
-loop unless a real pilot makes one of them a blocker.
+Finish the first demo before adding more integrations. Pick the next workflow from the setup failures and repeated QA tasks that coordinators actually hit. Keep Navisworks, Power BI and other provider work behind this until a real pilot shows one of them blocks users.
diff --git a/docs/security.md b/docs/security.md
index 35ecc32..6f91116 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -1,10 +1,10 @@
-# Security Model
+# Security model
-AEC Model Bridge implements a defense-in-depth security model to protect local models and filesystems from unauthorized or destructive actions by AI agents. The security posture relies on strict trust boundaries, local loopback restrictions, workspace sandboxing, input schema validation, and structured audit logs.
+AEC Model Bridge uses several layers to protect your models and files from unwanted or destructive actions by AI agents. The layers are: clear trust boundaries, loopback-only connections, a workspace sandbox, input checks, an approval step for changes, and audit logs.
---
-## 1. Trust Boundaries & Architecture
+## 1. Trust boundaries and architecture
```
┌─────────────────────────────────────────────────────────────┐
@@ -30,45 +30,47 @@ AEC Model Bridge implements a defense-in-depth security model to protect local m
└──────────┘└─────────┘└─────────┘└─────────┘└──────────┘
```
-The system coordinates several platform providers:
-1. **Unified Python MCP Server**: The central gateway. Runs locally, communicates via standard input/output (stdio) with the LLM host.
-2. **Revit Add-in**: Runs in-process inside Revit. Exposes a local HTTP port.
-3. **Rhino Bridge Add-in**: Runs in-process inside Rhino. Exposes HTTP port 3004.
-4. **IFC Parsing**: Executed in-process via `IfcOpenShell` (headless Python).
-5. **Speckle & APS Cloud Connections**: Connect to external APIs over HTTPS using OAuth-PKCE.
+The Revit add-in listens on port `3000` only in legacy mode. In the default mode it picks a dynamic port (see section 2).
+
+The system has these parts:
+1. **Unified Python MCP server**: the central gateway. It runs on your machine and talks to the AI client over standard input and output (stdio).
+2. **Revit add-in**: runs inside Revit and opens a local HTTP port.
+3. **Rhino bridge add-in**: runs inside Rhino and opens HTTP port 3004.
+4. **IFC parsing**: runs inside the Python server with `IfcOpenShell`. Revit is not needed.
+5. **Speckle and APS cloud connections**: call external APIs over HTTPS with OAuth-PKCE.
---
-## 2. Network Security & Local Boundary
+## 2. Network security and the local boundary
-To prevent remote exploitation, all desktop bridges bind strictly to the loopback address.
+All desktop bridges listen on the loopback address only.
-### Localhost Boundary
-- Add-ins bind exclusively to `127.0.0.1` (localhost).
-- They will reject external incoming connections.
-- They must **never** be exposed via public reverse proxies or port-forwarding.
+### Localhost boundary
+- Add-ins bind to `127.0.0.1` (localhost) only.
+- They reject connections from other machines.
+- Never expose them through a public reverse proxy or port forwarding.
-### Authentication Modes (Revit Add-in)
-The C# Revit bridge supports two runtime modes:
-1. **Legacy Mode (Default)**: Binds to fixed port `3000` with no authentication (relies entirely on the localhost boundary). Enabled by default unless configured otherwise.
-2. **Contract v2 Mode**: Runs with dynamic loopback ports and bearer token authorization. A random per-session bearer token (nonce) is generated at startup and written to local registry files. The Python MCP provider reads the registry file, obtains the port and token, and uses authorization headers for subsequent requests.
+### Authentication modes (Revit add-in)
+The C# Revit bridge has two modes:
+1. **Contract v2 mode (default)**: the add-in picks a dynamic loopback port and creates a random bearer token each session. It writes both to a local registry file. The Python MCP server reads that file and sends the token with every request.
+2. **Legacy mode (opt-in)**: set the add-in's environment variable `MCP_REVIT_LEGACY_PORT` to `true` or `1`. The add-in then binds to fixed port `3000` with no authentication and relies only on the localhost boundary. Use it only if an older client needs it.
---
-## 3. Workspace Sandboxing
+## 3. Workspace sandboxing
-All local filesystem activities (file reads, database exports, sheet prints) are sandboxed to explicitly configured directories.
+All local file work (file reads, database exports, sheet prints) stays inside the configured directories.
### Configuration
-The sandboxing behavior is driven by the following environment variables:
+Two environment variables control the sandbox:
-| Environment Variable | Python Config Field | Description |
+| Environment variable | Python config field | Description |
|---|---|---|
-| `MCP_REVIT_WORKSPACE_DIR` | `workspace_dir` | The default directory for writing outputs and log files. |
-| `MCP_REVIT_ALLOWED_DIRECTORIES` | `allowed_directories` | A semicolon-delimited (`;`) list of allowed directories. |
+| `MCP_REVIT_WORKSPACE_DIR` | `workspace_dir` | The default directory for generated files. Defaults to `~/Documents/AEC Model Bridge`. |
+| `MCP_REVIT_ALLOWED_DIRECTORIES` | `allowed_directories` | A list of allowed directories, separated by semicolons (`;`). Defaults to the workspace directory only. |
### Enforcement
-The `WorkspaceMonitor` class validates every path candidate before any filesystem operation:
+The `WorkspaceMonitor` class checks every path before any file operation:
```python
from pathlib import Path
@@ -84,36 +86,36 @@ safe_path = monitor.assert_in_workspace(Path("C:\\RevitProjects\\model.rvt")) #
unsafe_path = monitor.assert_in_workspace(Path("C:\\Windows\\System32\\cmd.exe"))
```
-### Path Traversal Guard
-The `WorkspaceMonitor` resolves candidate paths to absolute, canonical paths:
-- Resolves all symbolic links.
-- Evaluates relative path elements (`..`, `.`).
-- Asserts that the target resolved path is relative to one of the configured allowed directories (`path.is_relative_to(allowed_dir)`).
+### Path traversal guard
+The `WorkspaceMonitor` turns each path into an absolute, canonical path. It then:
+- Follows all symbolic links.
+- Resolves relative parts (`..`, `.`).
+- Checks that the result sits inside one of the allowed directories (`path.is_relative_to(allowed_dir)`).
---
-## 4. Input Validation & Schema Integrity
+## 4. Input validation and schema integrity
-All tool arguments are validated before passing them to backend providers.
-- **Pydantic Validation**: Every MCP tool has an associated Pydantic schema defining required parameters, strict data types, and value constraints.
-- **Malformed Input Rejection**: Inputs violating schemas are rejected immediately by the Python server, preventing malformed inputs from reaching the C# API thread.
+The server checks all tool arguments before it passes them to a provider.
+- **Pydantic validation**: every MCP tool has a Pydantic schema. It sets the required parameters, data types and value limits.
+- **Rejecting bad input**: the Python server rejects input that breaks the schema. Bad input does not reach the C# API thread.
---
-## 5. Audit Logging & Sensitive Data Redaction
+## 5. Audit logging and sensitive data redaction
-Every tool call (successful or failed) is recorded chronologically to an append-only audit trail.
+The audit recorder writes one line per tool call to an append-only file. See [Logging and audit](logging-and-audit.md) for what each log covers and for a caveat about which server writes the file.
-### Log Configuration
-- Configured via `MCP_REVIT_AUDIT_LOG` (defaults to `audit.log` in the working directory).
-- Controlled by `MCP_REVIT_LOG_LEVEL` (defaults to `INFO`).
+### Log configuration
+- Set the file with `MCP_REVIT_AUDIT_LOG`. The default is `audit.log` in the working directory of the server process.
+- Set the level with `MCP_REVIT_LOG_LEVEL`. The default is `INFO`.
-### Redaction Rules
-To prevent sensitive tokens, OAuth codes, and local directories from leaking into log files or LLM context windows, the `AuditRecorder` runs a recursive redaction step:
-- **Sensitive Keys**: Fields matching password, token, api_key, authorization, secret, client_secret, or auth codes are replaced with `<redacted>`.
-- **System Paths**: File path strings (both Windows and POSIX) are matched against regex patterns and replaced with `<redacted-path>`.
+### Redaction rules
+Audit entries and tool responses pass through a redaction step. It keeps tokens, OAuth codes and local directories out of log files and out of the AI's context:
+- **Sensitive keys**: fields such as password, token, api_key, authorization, secret, client_secret and auth codes become `<redacted>`.
+- **System paths**: Windows, UNC and POSIX file paths become `<redacted-path>`.
-Example serialized log entry:
+Example log entry:
```json
{
"timestamp": "2026-07-08T18:02:10.123456Z",
@@ -133,20 +135,21 @@ Example serialized log entry:
---
-## 6. Threat Model & Safety Checklist
+## 6. Threat model and safety checklist
-### In-Scope Guards
-- Path traversal exploits trying to read sensitive configuration or files.
-- Unauthorized cloud calls (credentials stored out-of-band in env vars/keyrings).
-- Malformed C# call execution leading to Revit process crashes (prevented by process boundary and input schema validation).
+### What the design guards against
+- Path traversal that tries to read sensitive files or settings.
+- Unauthorized cloud calls. Credentials stay outside the tool arguments, in environment variables or keyrings.
+- Malformed input that could crash Revit. The process boundary and input schemas prevent it.
-### Out-of-Scope (Host Machine Security)
-- Local network compromises (e.g. malicious software running on the same loopback).
-- Unauthorized physical access or user-level malware.
-- Vendor API bugs (Autodesk Revit, Rhino).
+### What is out of scope (host machine security)
+- Other software on the same machine that can reach the loopback port.
+- Physical access to the machine, and malware running as your user.
+- Bugs in vendor APIs (Autodesk Revit, Rhino).
-### Safety Checklist
-- [ ] Ensure `MCP_REVIT_WORKSPACE_DIR` is set to a dedicated folder.
-- [ ] Limit `MCP_REVIT_ALLOWED_DIRECTORIES` to only the required assets.
-- [ ] Confirm no bridge is configured to bind to `0.0.0.0` or shared port-forward.
-- [ ] Secure access permissions for the audit log path (`audit.log`).
+### Safety checklist
+- [ ] Set `MCP_REVIT_WORKSPACE_DIR` to a dedicated folder.
+- [ ] Limit `MCP_REVIT_ALLOWED_DIRECTORIES` to the folders you need.
+- [ ] Confirm no bridge listens on `0.0.0.0` or sits behind a port forward.
+- [ ] Restrict access to the audit log file (`audit.log` by default).
+- [ ] Keep `MCP_REVIT_APPROVAL_MODE` at `required`, so every model change needs an approved plan.