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
Reject missing snapshots in live mode; persist panel hub logs (#59)
A. Sam Mohammad12b96f17f0c0
diff --git a/docs/roadmap.md b/docs/roadmap.mdindex b55d4cc..d65cdb4 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -21,11 +21,12 @@ Effort labels below are relative estimates, not delivery dates.## First demo scope-The snapshot contract needs repair first: the add-in currently writes-`snapshots/snapshot-{GUID}.json` and returns a bare GUID, while the Python-modules load `snapshots/{snapshot_id}.json`. The add-in also uses its own-workspace environment, which can differ from the Python server's workspace.-Align the saved filename, returned identifier and workspace, and verify the+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 thesnapshot covers the categories required by the QA rules. Never silently replacea failed live extraction with generated mock data.diff --git a/packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.py b/packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.pyindex 600f878..726b769 100644--- a/packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.py+++ b/packages/mcp-server-revit/src/revit_mcp_server/modules/parameter_manager/module.py@@ -392,7 +392,8 @@ class ParameterManagerModule:def _get_elements(self, snapshot_id: str, workspace: Any) -> List[Dict[str, Any]]:if not snapshot_id:- from revit_mcp_server.semantic.engine import generate_mock_snapshot+ from revit_mcp_server.semantic.engine import generate_mock_snapshot, require_snapshot_or_mock+ require_snapshot_or_mock(snapshot_id, "parameter_manager")snap = generate_mock_snapshot()return [el.model_dump(by_alias=True) for el in snap.elements]data = _load_snapshot(snapshot_id, workspace)diff --git a/packages/mcp-server-revit/src/revit_mcp_server/modules/qaqc_checker/module.py b/packages/mcp-server-revit/src/revit_mcp_server/modules/qaqc_checker/module.pyindex 2861874..d64f9bf 100644--- a/packages/mcp-server-revit/src/revit_mcp_server/modules/qaqc_checker/module.py+++ b/packages/mcp-server-revit/src/revit_mcp_server/modules/qaqc_checker/module.py@@ -368,7 +368,8 @@ class QaqcCheckerModule:def _get_data(self, snapshot_id: str, workspace: Any):if not snapshot_id:- from revit_mcp_server.semantic.engine import generate_mock_snapshot+ from revit_mcp_server.semantic.engine import generate_mock_snapshot, require_snapshot_or_mock+ require_snapshot_or_mock(snapshot_id, "qaqc_checker")snap = generate_mock_snapshot()return ([el.model_dump(by_alias=True) for el in snap.elements],diff --git a/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.py b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.pyindex 0b500aa..6859053 100644--- a/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.py+++ b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.py@@ -34,7 +34,8 @@ def _ws_dir(workspace: Any) -> Path:def _get_data(snapshot_id: str, workspace: Any):if not snapshot_id:- from revit_mcp_server.semantic.engine import generate_mock_snapshot+ from revit_mcp_server.semantic.engine import generate_mock_snapshot, require_snapshot_or_mock+ require_snapshot_or_mock(snapshot_id, "report_generator")snap = generate_mock_snapshot()return ([el.model_dump(by_alias=True) for el in snap.elements],@@ -61,6 +62,49 @@ def _match_element(el: Dict[str, Any], filter_dsl: Dict[str, Any]) -> bool:return Falsereturn True+def _load_source(snapshot_id: str, workspace: Any) -> Dict[str, Any]:+ """Document identity of the snapshot, so a report says what it describes."""+ if not snapshot_id:+ return {"doc_title": "Generated mock data (not a live model)", "doc_guid": "mock-doc"}+ path = _ws_dir(workspace) / "snapshots" / f"{snapshot_id}.json"+ try:+ with open(path, encoding="utf-8") as f:+ data = json.load(f)+ except (OSError, ValueError):+ return {}+ return data.get("source", {}) or {}+++def _write_summary_sheet(ws: Any, snapshot_id: str, source: Dict[str, Any], element_count: int, issues: List[Dict[str, Any]]) -> None:+ from datetime import datetime, timezone++ rows = [+ ("Snapshot ID", snapshot_id or "(mock)"),+ ("Document", source.get("doc_title") or source.get("title") or ""),+ ("Document GUID", source.get("doc_guid", "")),+ ("Report generated (UTC)", datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")),+ ("Elements in report", element_count),+ ("QA/QC issues", len(issues)),+ ]+ for label, count in sorted(_count_by(issues, "severity").items()):+ rows.append((f" {label or 'unspecified'} severity", count))+ for label, count in sorted(_count_by(issues, "status").items()):+ rows.append((f" status: {label or 'unspecified'}", count))+ _write_header(ws, ["Item", "Value"])+ ws.column_dimensions["A"].width = 28+ ws.column_dimensions["B"].width = 48+ for row in rows:+ ws.append(list(row))+++def _count_by(issues: List[Dict[str, Any]], key: str) -> Dict[str, int]:+ counts: Dict[str, int] = {}+ for issue in issues:+ value = str(issue.get(key, "") or "")+ counts[value] = counts.get(value, 0) + 1+ return counts++def _write_header(ws: Any, headers: List[str]) -> None:for col, title in enumerate(headers, 1):cell = ws.cell(row=1, column=col, value=title)@@ -99,10 +143,14 @@ class ReportGeneratorModule:matched = [el for el in elements if _match_element(el, filter_dsl)]wb = openpyxl.Workbook()+ issues = _load_qaqc_issues(workspace) if include_qaqc else []++ ws_summary = wb.active+ ws_summary.title = "Summary"+ _write_summary_sheet(ws_summary, snapshot_id, _load_source(snapshot_id, workspace), len(matched), issues)# --- Sheet 1: Elements ---- ws_el = wb.active- ws_el.title = "Elements"+ ws_el = wb.create_sheet("Elements")el_headers = ["UID", "Element ID", "Category", "Family", "Type Name", "Level UID", "Workset"]_write_header(ws_el, el_headers)for r, el in enumerate(matched, 2):@@ -144,7 +192,6 @@ class ReportGeneratorModule:ws_qa = wb.create_sheet("QA_QC Issues")qa_headers = ["Issue ID", "Rule ID", "Severity", "Element UID", "Label", "Message", "Status", "Created At"]_write_header(ws_qa, qa_headers)- issues = _load_qaqc_issues(workspace)for r, issue in enumerate(issues, 2):ws_qa.append([issue.get("id", ""),diff --git a/packages/mcp-server-revit/src/revit_mcp_server/panel_server.py b/packages/mcp-server-revit/src/revit_mcp_server/panel_server.pyindex 91536a3..67ec2af 100644--- a/packages/mcp-server-revit/src/revit_mcp_server/panel_server.py+++ b/packages/mcp-server-revit/src/revit_mcp_server/panel_server.py@@ -19,6 +19,8 @@ import jsonimport loggingimport osimport shutil+from logging.handlers import RotatingFileHandler+from pathlib import Pathfrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServerfrom typing import Any, Dict@@ -78,6 +80,60 @@ def _run_tool_sync(registry, approval_provider, name: str, arguments: Dict[str,return asyncio.run(_run())+def collect_diagnostics(workspace_dir: Path) -> Dict[str, Any]:+ """Install-to-first-check status: one entry per thing that can block a first run.++ Each check carries a ``next_step`` so the panel can show a specific recovery+ action instead of a generic connection error.+ """+ from .bridge.discovery import available_host_versions+ from .config import BridgeMode++ checks = []++ def add(check_id: str, ok: bool, detail: str, next_step: str = "") -> None:+ checks.append({"id": check_id, "ok": ok, "detail": detail, "next_step": "" if ok else next_step})++ add("hub", True, "Panel hub is running.")++ if config.mode == BridgeMode.mock:+ add(+ "mode", False,+ "Hub is in mock mode: tools return generated sample data, not your Revit model.",+ "Set MCP_REVIT_MODE=bridge and restart the hub.",+ )+ else:+ add("mode", True, f"Hub mode is '{config.mode.value}'.")+ versions = available_host_versions("revit")+ add(+ "revit_bridge", bool(versions),+ f"Live Revit bridge(s): {', '.join(versions)}." if versions else "No live Revit bridge found.",+ "Open Revit with the AEC Model Bridge add-in loaded and an active project, then refresh. "+ "If Revit is open, check that the add-in matches your Revit version (docs/install.md).",+ )++ try:+ workspace_dir.mkdir(parents=True, exist_ok=True)+ probe = workspace_dir / ".diagnostics-write-test"+ probe.write_text("ok", encoding="utf-8")+ probe.unlink()+ add("workspace", True, f"Workspace is writable: {workspace_dir}")+ except OSError as e:+ add(+ "workspace", False, f"Workspace is not writable: {workspace_dir} ({e.strerror or e})",+ "Set MCP_REVIT_WORKSPACE_DIR to a folder you can write to and restart the hub.",+ )++ claude_ok = bool(config.anthropic_api_key) or shutil.which("claude") is not None+ add(+ "ai_provider", claude_ok,+ "An AI provider is available for panel chat." if claude_ok else "No AI provider for panel chat.",+ "Set MCP_REVIT_ANTHROPIC_API_KEY, or install and sign in to the claude CLI, then restart Revit.",+ )++ return {"ok": all(c["ok"] for c in checks), "checks": checks}++class PanelRequestHandler(BaseHTTPRequestHandler):registry = Noneapproval_provider = None@@ -98,6 +154,9 @@ class PanelRequestHandler(BaseHTTPRequestHandler):if self.path == "/health":self._send_json(200, {"status": "healthy", "tools": len(self.registry.get_all_tools())})return+ if self.path == "/diagnostics":+ self._send_json(200, collect_diagnostics(self.workspace.allowed_directories[0]))+ returnif self.path == "/reports":self._handle_list_reports()return@@ -230,8 +289,39 @@ def build_server(port: int | None = None, workspace: WorkspaceMonitor | None = Nreturn server+def default_log_path() -> Path:+ """``%APPDATA%/AECModelBridge/Logs/panel-hub.log``, beside the add-in's bridge.jsonl."""+ appdata = os.getenv("APPDATA")+ base = Path(appdata) if appdata else Path.home() / ".local" / "share"+ return base / "AECModelBridge" / "Logs" / "panel-hub.log"+++def configure_file_logging(log_path: Path | None = None) -> Path | None:+ """Persist hub logs to a rotating file.++ The add-in launches the hub without capturing stdout/stderr, so without a+ file handler failures such as a stale plan state would be invisible.+ Returns the log path, or None if the file could not be opened (logging to a+ file must never stop the hub from starting).+ """+ path = log_path or default_log_path()+ try:+ path.parent.mkdir(parents=True, exist_ok=True)+ handler = RotatingFileHandler(path, maxBytes=1_000_000, backupCount=3, encoding="utf-8")+ except OSError:+ logger.warning("Could not open panel hub log file %s", path, exc_info=True)+ return None+ handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))+ package_logger = logging.getLogger(__name__.rsplit(".", 1)[0])+ package_logger.addHandler(handler)+ if package_logger.getEffectiveLevel() > logging.INFO:+ package_logger.setLevel(logging.INFO)+ return path++def run_panel_server() -> None:"""Entry point for running the panel HTTP shim as a standalone process."""+ configure_file_logging()server = build_server()logger.info("Panel HTTP shim listening on http://127.0.0.1:%d", server.server_address[1])try:diff --git a/packages/mcp-server-revit/src/revit_mcp_server/semantic/engine.py b/packages/mcp-server-revit/src/revit_mcp_server/semantic/engine.pyindex cfd7d22..8d71a2d 100644--- a/packages/mcp-server-revit/src/revit_mcp_server/semantic/engine.py+++ b/packages/mcp-server-revit/src/revit_mcp_server/semantic/engine.py@@ -18,6 +18,24 @@ from revit_mcp_server.semantic.models import (logger = logging.getLogger(__name__)++def require_snapshot_or_mock(snapshot_id: str, tool: str) -> None:+ """Refuse to fall back to generated mock data unless mock mode is explicit.++ Callers invoke this when ``snapshot_id`` is empty. In bridge (live) mode an+ omitted snapshot must not be answered with synthetic data that looks like+ findings about the open model.+ """+ from revit_mcp_server.config import BridgeMode, config++ if config.mode != BridgeMode.mock:+ raise ValueError(+ f"{tool} requires a snapshot_id when connected to Revit (mode='{config.mode.value}'). "+ "Capture one first with the snapshot tool and pass its snapshot_id; "+ "generated mock data is only used when MCP_REVIT_MODE=mock."+ )++def generate_mock_snapshot() -> Snapshot:snapshot_id = f"01J{uuid.uuid4().hex[:23].upper()}"taken_at = datetime.now(timezone.utc)@@ -164,27 +182,61 @@ def generate_mock_snapshot() -> Snapshot:counts=counts)+def _store_snapshot_file(workspace: Any, snapshot_id: str, source_path: Any) -> None:+ """Make sure ``snapshots/{snapshot_id}.json`` exists in the Python workspace.++ The add-in writes under its own workspace environment, which can differ from+ this process's; copy the file across when they do.+ """+ import shutil+ from pathlib import Path++ snapshots_dir = workspace.allowed_directories[0] / "snapshots"+ snapshots_dir.mkdir(parents=True, exist_ok=True)+ target = snapshots_dir / f"{snapshot_id}.json"+ if source_path and Path(source_path).resolve() != target.resolve() and not target.exists():+ shutil.copyfile(source_path, target)++async def snapshot_take(workspace: Any, bridge_client_or_provider: Any = None) -> Snapshot:- # Check if we should execute a real snapshot or generate a mock+ from revit_mcp_server.config import BridgeMode, config++ live = config.mode != BridgeMode.mockif bridge_client_or_provider and hasattr(bridge_client_or_provider, "execute_tool"):try:- # Call C# execute snapshotres = await bridge_client_or_provider.execute_tool("revit_extract_snapshot", {})if isinstance(res, dict) and "snapshot" in res:return Snapshot(**res["snapshot"])+ if isinstance(res, dict) and res.get("snapshot_id") and res.get("path"):+ # Add-in result: the snapshot was written to disk, not returned inline.+ import json++ with open(res["path"], encoding="utf-8") as f:+ snapshot = Snapshot(**json.load(f))+ _store_snapshot_file(workspace, snapshot.snapshot_id, res["path"])+ return snapshot+ if live:+ raise RuntimeError(f"Unexpected result from Revit snapshot extraction: {sorted(res) if isinstance(res, dict) else type(res).__name__}")except Exception as e:+ if live:+ raise RuntimeError(+ f"Could not capture a live snapshot from Revit: {e}. "+ "No mock data is substituted in bridge mode."+ ) from elogger.warning(f"Failed to extract snapshot from Revit host: {e}. Falling back to mock snapshot.")-+ elif live:+ raise RuntimeError("No Revit provider is available to capture a live snapshot; no mock data is substituted in bridge mode.")+snapshot = generate_mock_snapshot()-+# Store snapshot in workspace/snapshots foldersnapshots_dir = workspace.allowed_directories[0] / "snapshots"snapshots_dir.mkdir(parents=True, exist_ok=True)snapshot_path = snapshots_dir / f"{snapshot.snapshot_id}.json"-+with open(snapshot_path, "w", encoding="utf-8") as f:f.write(snapshot.model_dump_json(by_alias=True, indent=2))-+return snapshotdef snapshot_query(snapshot: Snapshot, filter_dsl: Dict[str, Any]) -> List[ElementRecord]:diff --git a/packages/mcp-server-revit/tests/test_panel_server.py b/packages/mcp-server-revit/tests/test_panel_server.pyindex 0261b6a..6a90b7e 100644--- a/packages/mcp-server-revit/tests/test_panel_server.py+++ b/packages/mcp-server-revit/tests/test_panel_server.py@@ -285,3 +285,49 @@ def test_agent_chat_no_provider_available_returns_error_without_dispatch(running}native_mock.assert_not_called()bridge_mock.assert_not_called()+++def test_configure_file_logging_persists_package_logs(tmp_path):+ import logging++ log_file = tmp_path / "Logs" / "panel-hub.log"+ path = panel_server.configure_file_logging(log_file)+ pkg_logger = logging.getLogger("revit_mcp_server")+ try:+ assert path == log_file+ logging.getLogger("revit_mcp_server.panel_server").error("stale plan boom")+ for h in pkg_logger.handlers:+ h.flush()+ assert "stale plan boom" in log_file.read_text(encoding="utf-8")+ finally:+ for h in list(pkg_logger.handlers):+ if getattr(h, "baseFilename", None) == str(log_file):+ pkg_logger.removeHandler(h)+ h.close()+++def test_configure_file_logging_tolerates_unwritable_path(tmp_path):+ blocker = tmp_path / "file"+ blocker.write_text("x")+ assert panel_server.configure_file_logging(blocker / "sub" / "panel-hub.log") is None+++def test_diagnostics_flags_mock_mode_with_next_step(running_server):+ status, body = _get(running_server, "/diagnostics")+ assert status == 200+ checks = {c["id"]: c for c in body["checks"]}+ assert checks["hub"]["ok"] is True+ assert checks["workspace"]["ok"] is True+ assert checks["mode"]["ok"] is False and "MCP_REVIT_MODE=bridge" in checks["mode"]["next_step"]+ assert body["ok"] is False+++def test_diagnostics_reports_missing_revit_bridge(running_server, monkeypatch):+ from revit_mcp_server.config import BridgeMode++ monkeypatch.setattr(panel_server.config, "mode", BridgeMode.bridge)+ monkeypatch.setattr("revit_mcp_server.bridge.discovery.available_host_versions", lambda *_a, **_k: [])+ status, body = _get(running_server, "/diagnostics")+ checks = {c["id"]: c for c in body["checks"]}+ assert checks["revit_bridge"]["ok"] is False+ assert "add-in" in checks["revit_bridge"]["next_step"]diff --git a/packages/mcp-server-revit/tests/test_qaqc_checker.py b/packages/mcp-server-revit/tests/test_qaqc_checker.pyindex 9855cd4..94ac7cb 100644--- a/packages/mcp-server-revit/tests/test_qaqc_checker.py+++ b/packages/mcp-server-revit/tests/test_qaqc_checker.py@@ -144,3 +144,11 @@ def test_resolve_nonexistent_issue_raises(module, workspace):module.run_check(workspace=workspace)with pytest.raises(ValueError, match="not found"):module.resolve_issue(issue_id="does-not-exist", workspace=workspace)+++def test_run_check_without_snapshot_rejected_in_bridge_mode(module, workspace, monkeypatch):+ from revit_mcp_server.config import BridgeMode, config++ monkeypatch.setattr(config, "mode", BridgeMode.bridge)+ with pytest.raises(ValueError, match="requires a snapshot_id"):+ module.run_check(snapshot_id="", workspace=workspace)diff --git a/packages/mcp-server-revit/tests/test_report_generator.py b/packages/mcp-server-revit/tests/test_report_generator.pyindex f7d6d36..d304176 100644--- a/packages/mcp-server-revit/tests/test_report_generator.py+++ b/packages/mcp-server-revit/tests/test_report_generator.py@@ -103,3 +103,16 @@ def test_export_excel_custom_filename(module, workspace, tmp_path):workspace=workspace,)assert Path(result["output_file"]).name == "custom_report.xlsx"+++def test_export_excel_has_summary_sheet_first(tmp_path):+ import openpyxl+ from types import SimpleNamespace++ ws = SimpleNamespace(allowed_directories=[tmp_path])+ result = ReportGeneratorModule().export_excel(workspace=ws)+ wb = openpyxl.load_workbook(result["output_file"])+ assert wb.sheetnames[0] == "Summary"+ values = {row[0].value: row[1].value for row in wb["Summary"].iter_rows(min_row=2)}+ assert values["Snapshot ID"] == "(mock)"+ assert "mock" in values["Document"].lower()diff --git a/packages/mcp-server-revit/tests/test_semantic_engine.py b/packages/mcp-server-revit/tests/test_semantic_engine.pyindex 918ad2e..d1b83ed 100644--- a/packages/mcp-server-revit/tests/test_semantic_engine.py+++ b/packages/mcp-server-revit/tests/test_semantic_engine.py@@ -124,3 +124,54 @@ async def test_semantic_provider_and_mapper_registration(tmp_path):assert trans_res["translated_id"] is not None# door-uid-0001 is a GUID prefix-based UID, so it maps deterministicallyassert len(trans_res["translated_id"]) == 22 # IFC compressed GUID length+++class _FakeRevit:+ def __init__(self, result=None, error=None):+ self.result, self.error = result, error++ async def execute_tool(self, name, arguments):+ if self.error:+ raise self.error+ return self.result+++def _bridge_mode(monkeypatch):+ from revit_mcp_server.config import BridgeMode, config++ monkeypatch.setattr(config, "mode", BridgeMode.bridge)+++def test_snapshot_take_bridge_mode_never_substitutes_mock(tmp_path, monkeypatch):+ import asyncio+ from types import SimpleNamespace+ from revit_mcp_server.semantic import engine++ _bridge_mode(monkeypatch)+ ws = SimpleNamespace(allowed_directories=[tmp_path])+ with pytest.raises(RuntimeError, match="No mock data"):+ asyncio.run(engine.snapshot_take(ws, _FakeRevit(error=ConnectionError("down"))))+ with pytest.raises(RuntimeError, match="No Revit provider"):+ asyncio.run(engine.snapshot_take(ws, None))+ assert not (tmp_path / "snapshots").exists()+++def test_snapshot_take_ingests_addin_file_into_workspace(tmp_path, monkeypatch):+ import asyncio+ import json+ from types import SimpleNamespace+ from revit_mcp_server.semantic import engine++ _bridge_mode(monkeypatch)+ addin_dir = tmp_path / "addin"+ addin_dir.mkdir()+ written = addin_dir / "abc123.json"+ written.write_text(json.dumps({"schema": "amb.snapshot/1", "snapshot_id": "abc123", "elements": []}), encoding="utf-8")+ workspace_dir = tmp_path / "ws"+ workspace_dir.mkdir()+ ws = SimpleNamespace(allowed_directories=[workspace_dir])++ snap = asyncio.run(engine.snapshot_take(ws, _FakeRevit(result={"snapshot_id": "abc123", "path": str(written)})))++ assert snap.snapshot_id == "abc123"+ assert (workspace_dir / "snapshots" / "abc123.json").exists()diff --git a/packages/revit-bridge-addin/src/Bridge/BridgeCommandFactory.cs b/packages/revit-bridge-addin/src/Bridge/BridgeCommandFactory.csindex 9ca9294..38286ed 100644--- a/packages/revit-bridge-addin/src/Bridge/BridgeCommandFactory.cs+++ b/packages/revit-bridge-addin/src/Bridge/BridgeCommandFactory.cs@@ -4442,7 +4442,7 @@ public static class BridgeCommandFactoryvar workspaceDir = Environment.GetEnvironmentVariable("MCP_REVIT_WORKSPACE_DIR") ?? Path.GetTempPath();var snapshotDir = Path.Combine(workspaceDir, "snapshots");Directory.CreateDirectory(snapshotDir);- var snapshotPath = Path.Combine(snapshotDir, $"snapshot-{snapshotId}.json");+ var snapshotPath = Path.Combine(snapshotDir, $"{snapshotId}.json");var elementsToExtract = new List<Element>();var dirtyIds = DocumentDirtyTracker.GetDirtyUniqueIds();