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.

feat(modules): implement Report Generator — Excel multi-sheet export, SQLite summary, QA/QC coloring (P14.1-P14.2)

A. Sam Mohammadabe17e9a779f
diff --git a/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/__init__.py b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/__init__.py
new file mode 100644
index 0000000..85d7445
--- /dev/null
+++ b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/__init__.py
@@ -0,0 +1 @@
+# report_generator
diff --git a/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.json b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.json
new file mode 100644
index 0000000..7890c41
--- /dev/null
+++ b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.json
@@ -0,0 +1,56 @@
+{
+ "id": "report_generator",
+ "name": "Report Generator",
+ "version": "1.0.0",
+ "schema_version": 1,
+ "min_hub_version": "1.2.0",
+ "description": "Management-grade reporting (W8, W16): Excel workbooks with elements/params/QA findings, schedule-able via jobs.",
+ "author": "AEC Model Bridge",
+ "license": "GPL-3.0-or-later",
+ "requires_providers": ["revit", "semantic"],
+ "permissions": ["model.read", "files.write"],
+ "commands": [
+ {
+ "id": "export_excel",
+ "title": "Export to Excel",
+ "surface": ["mcp"],
+ "execution_mode": "sync",
+ "is_mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "snapshot_id": {"type": "string"},
+ "element_filter": {"type": "object", "description": "DSL filter to select elements."},
+ "param_names": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "Parameter columns to include.",
+ "default": []
+ },
+ "include_qaqc": {
+ "type": "boolean",
+ "default": true,
+ "description": "Include a QA/QC findings sheet."
+ },
+ "output_filename": {"type": "string", "default": "model_report.xlsx"}
+ },
+ "required": []
+ }
+ },
+ {
+ "id": "export_sqlite_summary",
+ "title": "Export SQLite Summary",
+ "surface": ["mcp"],
+ "execution_mode": "sync",
+ "is_mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "snapshot_id": {"type": "string"},
+ "output_filename": {"type": "string", "default": "model_data.db"}
+ },
+ "required": []
+ }
+ }
+ ]
+}
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.py
new file mode 100644
index 0000000..42a9636
--- /dev/null
+++ b/packages/mcp-server-revit/src/revit_mcp_server/modules/report_generator/module.py
@@ -0,0 +1,250 @@
+"""
+report_generator module — P14 Excel / SQLite reporting (W8, W16).
+
+Commands:
+ export_excel — Generate a multi-sheet .xlsx: Elements, Params, QA Findings.
+ export_sqlite_summary — Write elements + types into a fresh SQLite db.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import openpyxl
+from openpyxl.styles import Font, PatternFill, Alignment
+from openpyxl.utils import get_column_letter
+
+logger = logging.getLogger(__name__)
+
+_HEADER_FONT = Font(bold=True, color="FFFFFF")
+_HEADER_FILL = PatternFill("solid", fgColor="2C5F8A")
+
+SEVERITY_COLORS = {
+ "error": "FFE0E0",
+ "warning": "FFF3CD",
+ "info": "E0F0FF",
+}
+
+
+def _ws_dir(workspace: Any) -> Path:
+ return workspace.allowed_directories[0]
+
+def _get_data(snapshot_id: str, workspace: Any):
+ if not snapshot_id:
+ from revit_mcp_server.semantic.engine import generate_mock_snapshot
+ snap = generate_mock_snapshot()
+ return (
+ [el.model_dump(by_alias=True) for el in snap.elements],
+ [t.model_dump() for t in snap.types],
+ )
+ path = _ws_dir(workspace) / "snapshots" / f"{snapshot_id}.json"
+ if not path.exists():
+ raise ValueError(f"Snapshot '{snapshot_id}' not found.")
+ with open(path, encoding="utf-8") as f:
+ data = json.load(f)
+ return data.get("elements", []), data.get("types", [])
+
+def _match_element(el: Dict[str, Any], filter_dsl: Dict[str, Any]) -> bool:
+ if not filter_dsl:
+ return True
+ for key, val in filter_dsl.items():
+ if key == "category":
+ cats = val if isinstance(val, list) else [val]
+ if el.get("category") not in cats:
+ return False
+ elif key == "family" and el.get("family") != val:
+ return False
+ elif key == "type_name" and el.get("type_name") != val:
+ return False
+ return True
+
+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)
+ cell.font = _HEADER_FONT
+ cell.fill = _HEADER_FILL
+ cell.alignment = Alignment(horizontal="center")
+ ws.column_dimensions[get_column_letter(col)].width = max(12, len(title) + 2)
+
+def _load_qaqc_issues(workspace: Any) -> List[Dict[str, Any]]:
+ db_path = _ws_dir(workspace) / "qaqc_issues.db"
+ if not db_path.exists():
+ return []
+ conn = sqlite3.connect(str(db_path))
+ conn.row_factory = sqlite3.Row
+ rows = conn.execute("SELECT * FROM issues").fetchall()
+ conn.close()
+ return [dict(r) for r in rows]
+
+
+class ReportGeneratorModule:
+
+ def export_excel(
+ self,
+ snapshot_id: str = "",
+ element_filter: Dict[str, Any] = None,
+ param_names: List[str] = None,
+ include_qaqc: bool = True,
+ output_filename: str = "model_report.xlsx",
+ workspace: Any = None,
+ **_,
+ ) -> Dict[str, Any]:
+ elements, types = _get_data(snapshot_id, workspace)
+ filter_dsl = element_filter or {}
+ param_names = param_names or []
+
+ matched = [el for el in elements if _match_element(el, filter_dsl)]
+
+ wb = openpyxl.Workbook()
+
+ # --- Sheet 1: Elements ---
+ ws_el = wb.active
+ ws_el.title = "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):
+ ws_el.append([
+ el.get("uid", ""),
+ el.get("element_id", ""),
+ el.get("category", ""),
+ el.get("family", ""),
+ el.get("type_name", ""),
+ el.get("level_uid", ""),
+ el.get("workset", ""),
+ ])
+
+ # --- Sheet 2: Parameters ---
+ if param_names:
+ ws_param = wb.create_sheet("Parameters")
+ param_headers = ["UID", "Category", "Type Name"] + param_names
+ _write_header(ws_param, param_headers)
+ for r, el in enumerate(matched, 2):
+ row = [el.get("uid", ""), el.get("category", ""), el.get("type_name", "")]
+ for pname in param_names:
+ pinfo = (el.get("params", {}) or {}).get(pname)
+ row.append(pinfo.get("v") if pinfo else "")
+ ws_param.append(row)
+
+ # --- Sheet 3: Types ---
+ ws_types = wb.create_sheet("Types")
+ _write_header(ws_types, ["Family", "Type Name", "Category", "Family Source"])
+ for t in types:
+ ws_types.append([
+ t.get("family", ""),
+ t.get("type_name", ""),
+ t.get("category", ""),
+ t.get("family_source", "loadable"),
+ ])
+
+ # --- Sheet 4: QA/QC Issues (optional) ---
+ if include_qaqc:
+ 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", ""),
+ issue.get("rule_id", ""),
+ issue.get("severity", ""),
+ issue.get("element_uid", ""),
+ issue.get("label", ""),
+ issue.get("message", ""),
+ issue.get("status", ""),
+ issue.get("created_at", ""),
+ ])
+ # Color row by severity
+ sev = issue.get("severity", "")
+ fill_color = SEVERITY_COLORS.get(sev)
+ if fill_color:
+ fill = PatternFill("solid", fgColor=fill_color)
+ for col in range(1, len(qa_headers) + 1):
+ ws_qa.cell(row=r, column=col).fill = fill
+
+ # --- Save ---
+ out_path = _ws_dir(workspace) / output_filename
+ wb.save(str(out_path))
+
+ return {
+ "status": "exported",
+ "output_file": str(out_path),
+ "element_count": len(matched),
+ "type_count": len(types),
+ "sheets": wb.sheetnames,
+ }
+
+ def export_sqlite_summary(
+ self,
+ snapshot_id: str = "",
+ output_filename: str = "model_data.db",
+ workspace: Any = None,
+ **_,
+ ) -> Dict[str, Any]:
+ elements, types = _get_data(snapshot_id, workspace)
+ out_path = _ws_dir(workspace) / output_filename
+
+ conn = sqlite3.connect(str(out_path))
+ conn.executescript("""
+ DROP TABLE IF EXISTS elements;
+ DROP TABLE IF EXISTS types;
+ CREATE TABLE elements (
+ uid TEXT PRIMARY KEY,
+ element_id TEXT,
+ category TEXT,
+ family TEXT,
+ type_name TEXT,
+ level_uid TEXT,
+ workset TEXT,
+ host_uid TEXT
+ );
+ CREATE TABLE types (
+ family TEXT,
+ type_name TEXT,
+ category TEXT,
+ family_source TEXT
+ );
+ """)
+
+ conn.executemany(
+ "INSERT OR REPLACE INTO elements VALUES (?,?,?,?,?,?,?,?)",
+ [
+ (
+ el.get("uid", ""),
+ el.get("element_id", ""),
+ el.get("category", ""),
+ el.get("family", ""),
+ el.get("type_name", ""),
+ el.get("level_uid", ""),
+ el.get("workset", ""),
+ el.get("host_uid", ""),
+ )
+ for el in elements
+ ]
+ )
+
+ conn.executemany(
+ "INSERT INTO types VALUES (?,?,?,?)",
+ [
+ (
+ t.get("family", ""),
+ t.get("type_name", ""),
+ t.get("category", ""),
+ t.get("family_source", "loadable"),
+ )
+ for t in types
+ ]
+ )
+
+ conn.commit()
+ conn.close()
+
+ return {
+ "status": "exported",
+ "output_file": str(out_path),
+ "element_count": len(elements),
+ "type_count": len(types),
+ }
diff --git a/packages/mcp-server-revit/tests/test_report_generator.py b/packages/mcp-server-revit/tests/test_report_generator.py
new file mode 100644
index 0000000..540c978
--- /dev/null
+++ b/packages/mcp-server-revit/tests/test_report_generator.py
@@ -0,0 +1,107 @@
+"""Tests for Phase 14 — Report Generator module (W8, W16)."""
+import importlib.util
+import json
+import sqlite3
+import pytest
+from pathlib import Path
+from revit_mcp_server.semantic.engine import generate_mock_snapshot
+
+
+def _load_mod(relpath: str, name: str):
+ p = Path(__file__).parent.parent / relpath
+ spec = importlib.util.spec_from_file_location(name, p)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+_rg = _load_mod("src/revit_mcp_server/modules/report_generator/module.py", "_rg_impl")
+ReportGeneratorModule = _rg.ReportGeneratorModule
+
+
+class MockWorkspace:
+ def __init__(self, tmp_path: Path):
+ self.allowed_directories = [tmp_path]
+
+
+def workspace(tmp_path):
+ return MockWorkspace(tmp_path)
+
+
+def module():
+ return ReportGeneratorModule()
+
+
+def test_export_excel_creates_file(module, workspace, tmp_path):
+ result = module.export_excel(
+ param_names=["Mark", "FireRating"],
+ include_qaqc=False,
+ workspace=workspace,
+ )
+ assert result["status"] == "exported"
+ out = Path(result["output_file"])
+ assert out.exists()
+ assert out.suffix == ".xlsx"
+ assert result["element_count"] == 6
+
+
+def test_export_excel_includes_params_sheet(module, workspace, tmp_path):
+ import openpyxl
+ result = module.export_excel(
+ param_names=["Mark"],
+ include_qaqc=False,
+ workspace=workspace,
+ )
+ wb = openpyxl.load_workbook(result["output_file"])
+ assert "Parameters" in wb.sheetnames
+ ws = wb["Parameters"]
+ headers = [ws.cell(1, col).value for col in range(1, ws.max_column + 1)]
+ assert "Mark" in headers
+
+
+def test_export_excel_with_element_filter(module, workspace):
+ result = module.export_excel(
+ element_filter={"category": "OST_Doors"},
+ include_qaqc=False,
+ workspace=workspace,
+ )
+ assert result["element_count"] == 1
+
+
+def test_export_excel_with_qaqc_no_issues(module, workspace):
+ """QA sheet should exist even with no issue store."""
+ import openpyxl
+ result = module.export_excel(include_qaqc=True, workspace=workspace)
+ wb = openpyxl.load_workbook(result["output_file"])
+ assert "QA_QC Issues" in wb.sheetnames
+
+
+def test_export_sqlite_creates_db(module, workspace, tmp_path):
+ result = module.export_sqlite_summary(workspace=workspace)
+ assert result["status"] == "exported"
+ db_path = Path(result["output_file"])
+ assert db_path.exists()
+
+ conn = sqlite3.connect(str(db_path))
+ count = conn.execute("SELECT COUNT(*) FROM elements").fetchone()[0]
+ conn.close()
+ assert count == 6
+
+
+def test_export_sqlite_type_table(module, workspace):
+ result = module.export_sqlite_summary(workspace=workspace)
+ conn = sqlite3.connect(result["output_file"])
+ types = conn.execute("SELECT * FROM types").fetchall()
+ conn.close()
+ assert len(types) >= 2
+
+
+def test_export_excel_custom_filename(module, workspace, tmp_path):
+ result = module.export_excel(
+ output_filename="custom_report.xlsx",
+ include_qaqc=False,
+ workspace=workspace,
+ )
+ assert Path(result["output_file"]).name == "custom_report.xlsx"