Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
Python aecai-agentsautodeskautomationbimclaudeifcmcpmcp-servermodel-context-protocolnavisworksrevitrevit-addinrevit-apirhino
docs: add demo runbook for the missing door Mark demo (#72)
A. Sam Mohammad34d937323519
diff --git a/docs/README.md b/docs/README.mdindex 92b74fa..bb33412 100644--- a/docs/README.md+++ b/docs/README.md@@ -14,6 +14,7 @@ Start with the [installation guide](install.md). The main [README](../README.md)- [versioning.md](versioning.md): version numbers, release tags and release assets.- [clash-triage.md](clash-triage.md): read-only matching of Navisworks clashes to Revit elements, with a confidence label (unverified on live projects).- [roadmap.md](roadmap.md): coordinator workflows, demo scope and the next fixes.+- [demo-runbook.md](demo-runbook.md): step-by-step script for the missing-door-Mark demo, with expected counts and a rejected-plan run.## For contributorsdiff --git a/docs/demo-runbook.md b/docs/demo-runbook.mdnew file mode 100644index 0000000..e37ca2e--- /dev/null+++ b/docs/demo-runbook.md@@ -0,0 +1,326 @@+# Demo runbook: missing door Marks++This is the script for the core demo: ask, plan, preview, approve in Revit,+verify, undo. It runs on a synthetic fixture with 12 doors that have no Mark+and 3 rooms that have no Number. It also covers a run where the plan is+rejected and nothing changes.++**Writes are untested in a real Revit.** An architecture review found that+`BridgeCommandFactory.CreateTransaction(Document, string)` in the add-in calls+itself, so as written on `main` every model write (including+`revit_set_parameter_value`) would recurse until Revit crashes. The fix is+hotfix PR #95, which is open and not merged. Do not run Step 6 or the undo+steps against anything you care about until #95 is merged and the add-in is+rebuilt from it, and treat the first real write on a throwaway copy as a test+in its own right. Steps 1 to 5 and the rejected-plan run do not write to the+model.++Nobody has run this end to end against live Revit yet. The expected counts come+from the [seeded defect manifest](../fixtures/canonical-model/seeded-defects.json)+and the rule pack, not from a recorded session. Record what you actually see+and treat any difference as a finding. Background on why the demo looks like+this is in the [roadmap](roadmap.md).++## How to read the status tags++- **Checked in code**: the tool or panel feature exists on `main` and I read+ how it behaves. That does not mean it has been seen working in Revit.+- **UNVERIFIED (live Revit)**: it needs a running Revit session with the+ add-in. Nothing in this runbook has been confirmed that way.+- **UNVERIFIED (unmerged)**: it depends on work that is not on `main`.+ Preview in the model is in open PR #64. Skip that step, or do it by hand,+ until it lands. Proof bundles and `plan_revert` (#62) and the draft-plan gate+ fix (#63) are merged, so they are tagged "checked in code" below, not+ unmerged. The write-path crash fix is open PR #95 (see above).++## What you need++- Windows with a supported Revit version (2024 to 2027) and the add-in+ installed. See the [install guide](install.md).+- The MCP server connected to an MCP client, and the Revit side panel open.+- A throwaway copy of the fixture. Never run this on a project model.+- Approval mode left at its default (`required`). Do not set+ `MCP_REVIT_APPROVAL_MODE=auto`; that turns the human check off.++Write down before you start: Revit version, git commit, date, and the document+name. The roadmap asks for these with every recorded run.++## Step 0: build the fixture++From the repository root, with Revit open and the add-in loaded:++```powershell+python scripts\revit\generate_canonical_test_model.py+```++The script saves to `fixtures/canonical-model/generated/canonical_test_model.rvt`.+If Revit does not activate the new document, open a clean project template+yourself and rerun with `--use-active-document`. Details are in the+[fixture README](../fixtures/canonical-model/README.md).++Expected: per the manifest, the last 12 generated doors have no Mark and the+last 3 generated rooms have no Number. The manifest also expects the core rule+pack to report 15 findings in total on this model (12 + 3). UNVERIFIED (live+Revit): the generator itself.++If it fails: confirm the add-in is loaded and a document is open. The script+looks for the bridge under `%LOCALAPPDATA%\AECModelBridge\registry\` and falls+back to `http://127.0.0.1:3000`. Save the generated model under a new name so+you can reopen a clean copy for the rejected-plan run.++## Step 1: capture a snapshot++Ask the assistant: "Take a snapshot of the active model." The tool is+`revit_extract_snapshot`. Keep the `snapshot_id` it returns; every check and+parameter call below needs it.++Why: on `main`, the QA checker and the parameter manager refuse to run in live+mode without a `snapshot_id` and tell you to capture one (change #59). They only+fall back to generated sample data when `MCP_REVIT_MODE=mock`. Sample data is not+your model, so do not run the demo in mock mode and call it live.++What to look for: a snapshot id comes back, with no error. I have not seen the+exact output, so I will not quote it. Note the id and the time.++If it fails:++- "requires a snapshot_id" means you skipped this step or the id was not passed.+- A connection error means the add-in is not running or the server cannot find+ it. Check the panel's status area, then see the install guide.+- The snapshot file must be readable by the Python server. The add-in and the+ server each have a workspace setting. If the server says the snapshot is not+ found, confirm both point at the same workspace folder. The roadmap flags this+ as something to verify, so treat it as a likely first failure.++UNVERIFIED (live Revit).++## Step 2: ask (find the problems)++Ask: "Run the core QA check on that snapshot and list the issues."++Tools: `qaqc_checker_run_check` (with `snapshot_id` and rule pack `core`), then+`qaqc_checker_list_issues`. Note the `doc_guid` that `run_check` returns and+pass it to `list_issues` together with `status` set to `open`. The issue store+is persistent and `list_issues` defaults to every document and every status, so+an unscoped call on a repeated demo, or after the doors are fixed, also returns+old and resolved findings and will not match the counts below.++Expected counts, from the manifest:++| Rule | Expected findings |+| --- | --- |+| `door_missing_mark` | 12 |+| `room_missing_number` | 3 |+| Total | 15 |++Other core rules may report findings on this model. The manifest lists several+rules the fixture cannot seed, so do not be alarmed by extra or absent lines for+other rules. Only the two rows above are the demo baseline.++If the counts differ: do not adjust the story to fit. Check that the snapshot+came from the fixture document, rebuild the fixture, and retake the snapshot. The+roadmap's bar is the same counts on two runs. If a run gives different numbers,+write down both.++Panel note: the panel's "Run Health Check" button on the Findings tab calls the+same check, but as written it sends no `snapshot_id`. In live mode that will be+rejected. Use the MCP client for this step. UNVERIFIED (live Revit) whether the+panel path works in your build.++## Step 3: plan++Ask: "Propose a unique Mark for each of the 12 doors without one, using the+pattern D-101 to D-112. Show me the exact values before anything is changed."++Agree the numbering pattern yourself first. The demo only works if the+coordinator chooses the rule; the assistant should not guess one.++Before building actions, get the numeric element ids. The QA findings carry+only `element_uid`, but `revit_set_parameter_value` needs the integer+`element_id`, and `plan_actions` does not convert one to the other. Look them up+in the snapshot: `parameter_manager_filter_params` (pass the snapshot id,+`param_name` `Mark`, and a filter for doors with an empty Mark) returns each+match with both `uid` and `element_id`; `model_inspector_ask` also returns+`element_id`. Match them to the 12 `element_uid` values from Step 2 and do not+guess ids. The add-in's snapshot writer includes `element_id`; that it comes+through correctly is UNVERIFIED (live Revit).++Tool: `plan_actions`, with one `revit_set_parameter_value` action per door+(`element_id`, `parameter_name` = `Mark`, `value`). On `main`, `plan_actions`+reads each door's current Mark and stores it as the plan's before-state.+`parameter_manager_plan_set_params` can also build a draft, but it sets one+value for every matched element, so it does not fit unique Marks. Use it only+if you want to show a shared value.++Expected: a plan with 12 actions, state `pending`, 12 distinct values, and an+empty before-state for each door.++Things to check before going further:++- Exactly 12 element ids, none of them rooms, and each one matches a finding's+ `element_uid` from Step 2.+- No duplicate values within the plan, and none that clash with the 48 doors that+ already have a Mark. The code does not check uniqueness of the proposed values+ for you. This is on the human.+- If a before-value shows as missing for an element, say so. Rollback in Step 8+ depends on it.++If it fails: an assistant that tries to change a parameter directly, without a+plan, should get an authorization error naming the missing `plan_id`. That is the+gate working. Go back and create the plan. If the assistant lists+`list_pending_plans` and your plan is not there, plan creation failed; ask it to+report the error text.++## Step 4: preview++Two previews, different status:++- **In the panel (checked in code)**: open the Plans tab and press Refresh. The+ plan appears with its state and a one-line list of the tools in it. The panel+ today shows tool names, not per-door old and new values. So read the+ old/new values from the assistant's plan output, and compare the count+ yourself.+- **In the model (UNVERIFIED, unmerged, PR #64)**: showing the pending change on+ the actual elements in Revit is not on `main`. Skip it for now, or select the+ 12 doors and eyeball them. Use `revit_select_by_unique_ids` with the 12+ `element_uid` values; it selects and zooms in the active view. Do not use+ `selection_tools_select_by_query` for this: it only writes the matching UIDs to+ `pending_selection.json` in the workspace, and nothing in the add-in reads that+ file, so nothing would be selected in Revit. Selecting is a Revit UI action.+ UNVERIFIED (live Revit).++Expected: 1 pending plan, 12 actions.++## Step 5: approve in Revit++In the panel's Plans tab, press Approve on the plan. The panel sends+`approve_plan` through the hub. The assistant cannot approve its own plan: the+approval tools are withheld from the native chat backend by design.++Expected: the plan leaves the pending list. The Run Log gets a `Plan approve`+entry as soon as you click, and a `Plans updated` entry after the refresh; both+are normal and neither proves the hub accepted the call. Nothing in the model has changed yet; approval only unlocks execution.++If it fails: an `Error: plan.approve` entry in the Run Log (or an error toast)+means the hub rejected the call. Any other Run Log entry is not a failure.+Press Refresh and check the plan's state. Do not approve a plan you+rejected; the code does not stop you from changing a plan's state, so check+the state each time.++UNVERIFIED (live Revit).++## Step 6: execute++Ask the assistant: "The plan is approved. Run it." Tool: `execute_plan`.++Expected: the result lists 12 actions, each executed. In the add-in each+`revit_set_parameter_value` call runs in its own transaction, which Revit's+Undo list should show as `AMB: Set Parameter Value`, one entry per door, not one+entry for the whole plan. The add-in only appends ` #<action id>` to the name+when the call carries an `action_id`, and `execute_plan` does not pass one, so+expect no suffix and 12 identical-looking entries. This is only reachable once+#95 is merged (see the top of this page). UNVERIFIED (live Revit).++If some actions fail: execution reports and continues. The plan is marked+`partial`, not `executed`, and the proof bundle's outcome is `partial` or+`failed`. Do not tell the audience it worked. Read which actions failed+(read-only or owned elements are the usual suspects), then go to Step 7 and look+at what changed.++## Step 7: verify++Take a new snapshot (Step 1 again, new id) and rerun the check on it. Never+verify with the old snapshot; it still shows the old values.++Expected after a clean run:++| Rule | Before | After |+| --- | --- | --- |+| `door_missing_mark` | 12 | 0 |+| `room_missing_number` | 3 | 3 (unchanged on purpose) |++The 3 room findings staying put is the point: the approval covered doors only,+and nothing else moved. Also read back two or three of the new Marks with+`revit_get_parameter_value` and compare with the plan.++If the door count is not 0: list the remaining issues and match them to the+plan's failed actions. Say what happened plainly. If the room count changed,+stop. Something outside the plan wrote to the model; check the+[audit logs](logging-and-audit.md) to match requested changes against what Revit+executed.++## Step 8: undo++There are two ways back. Use whichever you can show honestly.++1. **Revit Undo (checked in code that transactions are named, behavior+ UNVERIFIED)**. Immediately after execution, in the same Revit session, press+ Ctrl+Z. Because each parameter write is its own named transaction, you may+ need to press it 12 times. Take a fresh snapshot afterwards and expect the+ baseline of 12 and 3 again. ADR 0008 describes a single named transaction+ per plan; the code on `main` names one per action. The ADR and the code do+ not yet agree, so do not promise one-click undo.+2. **`rollback_plan` (checked in code)**. It only works on a plan in state+ `executed`, and it writes each recorded before-value back. One catch: it+ skips an action when no before-value was recorded, and reports that as a+ warning. These doors started empty. If the before-state is stored as empty,+ rollback may skip all 12 and leave the Marks in place. Read the warnings in+ the result and verify with a new snapshot. If it skipped them, use Ctrl+Z+ instead. UNVERIFIED (live Revit). The model-facing chat cannot call rollback;+ a person does it from the client.+3. **`plan_revert` (checked in code, merged in #62)**. It drafts a new pending+ plan from the proof bundle; you still approve and execute it. It refuses when+ an element has no recorded before-value, and an empty value counts as not+ recorded. These doors started with an empty Mark, so expect `plan_revert` to+ refuse here. Treat that as the documented behaviour, not a bug, and fall back+ to Ctrl+Z. It would work for a parameter that had a value before. Its+ write-back is UNVERIFIED (live Revit) and subject to #95 like every write.++Proof of the change: `get_proof_bundle(plan_id)` returns the proof file written+after `execute_plan` (see [proof and revert](proof-and-revert.md)). Pass+`snapshot_id` to `plan_actions` if you want the document identity in it. The+bundle is a server-side record, not an observation of the model, so the evidence+that the model really changed or reverted is still the two snapshots and the+check counts. UNVERIFIED (live Revit).++## Rejected-plan run++This proves a rejected plan leaves the model alone. Start from a clean copy of+the fixture (the baseline of 12 and 3) and a new snapshot.++1. Steps 1 to 4 as above. Note the snapshot id and the 12 before-values.+2. In the panel's Plans tab, press Reject. This sends `reject_plan`. The plan is+ closed and archived.+3. Ask the assistant to run it anyway. Expected: `execute_plan` refuses, saying+ the plan is `rejected`, not `approved`. A direct parameter write with that+ plan id is blocked the same way.+4. Take a new snapshot and rerun the check. Expected: 12 missing door Marks and 3+ missing room Numbers, exactly as in Step 2. Read two doors' Marks back: still+ empty.+5. Compare the new snapshot with the first one. Nothing should differ.+ `parameter_manager_diff_params` compares two snapshots and lists differences.+ Expected: no parameter differences.++If anything is different, that is a bug in the gate. Stop and capture the plan+file, the audit log and both snapshot ids.++## Quick reference: when it goes wrong++| What you see | What to say | What to do |+| --- | --- | --- |+| "requires a snapshot_id" | The tool is protecting us from sample data. | Take a snapshot, pass its id. |+| Counts are not 12 and 3 | The baseline is off; I am not going to hide that. | Rebuild the fixture, retake the snapshot, record both runs. |+| Error naming a missing or unapproved `plan_id` | The gate is blocking an unapproved write. | Create or approve the plan. |+| Approve does nothing in the panel | I will confirm the plan state before going on. | Refresh, look for an `Error:` entry in the Run Log, check the plan state. |+| Revit crashes or hangs on the first write | Known: write path is broken until #95. | Stop. Check that #95 is merged and the add-in rebuilt. |+| Some actions failed on execute | This is a partial result, not a finished fix. | Read the per-action errors, verify with a new snapshot. |+| Door count after is not 0 | Not everything was fixed. | List the remaining issues, match them to failed actions. |+| Rollback skipped actions | Rollback could not restore empty values. | Use Revit Undo, then verify with a new snapshot. |+| Anything touching rooms changed | Stop the demo. | Check the audit logs. |++## Record for each run++Date, commit, Revit version, fixture generation command, snapshot ids (before+and after), prompts used, the actual counts at each step, plan ids, and+what failed. The roadmap asks for the same list. Publish a recording only after a+run matches the expected counts twice.