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
"""
parameter_manager module — P9.1 + P9.2 Parameter/Family/Type Workflows.
Commands:
filter_params — Show parameter grid across matching elements.
diff_params — Diff parameter values between two snapshots.
plan_set_params — Validate params and produce an ActionPlan draft.
export_params_csv — Write param values to a CSV file in workspace.
import_params_csv — Read param updates from CSV → ActionPlan draft.
Validation rules (P9.2):
- readonly params are blocked
- type-vs-instance mismatches are blocked
- wrong storage type writes are blocked
- workshared-owned elements emit a skip warning (not a hard block without Revit)
"""
from __future__ import annotations
import csv
import json
import logging
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# Storage-type ↔ Python type mapping for validation
# ---------------------------------------------------------------------------
STORAGE_TYPE_VALIDATORS: Dict[str, type] = {
"String": str,
"Double": (int, float),
"Integer": int,
"ElementId": (int, str),
"Boolean": bool,
}
def _workspace_dir(workspace: Any) -> Path:
return workspace.allowed_directories[0]
def _confined(workspace: Any, *parts: str) -> Path:
"""Join parts under the workspace and refuse anything that resolves outside it.
Snapshot ids and file names come from the caller, and the draft-only tools run
without an approved plan, so '..', absolute paths and symlinks must not escape.
"""
base = _workspace_dir(workspace)
candidate = (base.joinpath(*parts)).resolve()
checker = getattr(workspace, "assert_in_workspace", None)
if checker is not None:
return checker(candidate)
if not candidate.is_relative_to(base.resolve()):
raise ValueError(f"{candidate} is outside the allowed workspace directories")
return candidate
def _load_snapshot(snapshot_id: str, workspace: Any) -> Dict[str, Any]:
path = _confined(workspace, "snapshots", f"{snapshot_id}.json")
if not path.exists():
raise ValueError(f"Snapshot '{snapshot_id}' not found.")
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
def _match_element(el: Dict[str, Any], filter_dsl: Dict[str, Any]) -> bool:
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
elif key == "level_uid" and el.get("level_uid") != val:
return False
elif key == "parameter":
pname = val.get("name")
params = el.get("params", {})
param = params.get(pname) if params else None
if val.get("empty") is True:
if param is not None and param.get("v") not in (None, ""):
return False
elif "value" in val:
if param is None or str(param.get("v")) != str(val["value"]):
return False
return True
def _validate_param_update(
el: Dict[str, Any],
param_name: str,
new_value: Any,
) -> Tuple[bool, Optional[str]]:
"""Returns (ok, reason_if_blocked)."""
params = el.get("params", {})
param_info = params.get(param_name)
if param_info is None:
return False, f"Parameter '{param_name}' does not exist on element {el['uid']}"
# Readonly block
if param_info.get("readonly", False):
return False, f"Parameter '{param_name}' is read-only on element {el['uid']}"
# Storage type check
storage = param_info.get("storage")
if storage and storage in STORAGE_TYPE_VALIDATORS:
expected_type = STORAGE_TYPE_VALIDATORS[storage]
if not isinstance(new_value, expected_type):
return False, (
f"Parameter '{param_name}' has storage type '{storage}' "
f"but received value of type '{type(new_value).__name__}'"
)
return True, None
def _make_action_plan(tool_name: str, args: Dict[str, Any], preview: Dict[str, Any]) -> Dict[str, Any]:
return {
"plan_type": "action_plan_draft",
"tool": tool_name,
"arguments": args,
"preview": preview,
"requires_approval": True,
"actions": _actions_from_planned(preview.get("planned", [])),
# Hand these to plan_actions (snapshot_id, skipped) so the proof bundle names the
# source document and lists what was left out and why.
"skipped": preview.get("blocked", []),
"snapshot_id": args.get("snapshot_id", ""),
}
def _actions_from_planned(planned: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Flatten a planned-updates list into `plan_actions`-ready tool calls.
One `revit_set_parameter_value` action per (element, parameter) pair, so the
caller can pass this straight to `plan_actions` — that path already captures
before-state and supports rollback for this tool, generalizing to any batch
size with no additional code.
"""
actions: List[Dict[str, Any]] = []
for entry in planned:
element_id = entry.get("element_id")
for pname, change in entry.get("updates", {}).items():
actions.append({
"tool": "revit_set_parameter_value",
"arguments": {
"element_id": element_id,
"parameter_name": pname,
"value": change.get("after"),
},
})
return actions
class ParameterManagerModule:
def filter_params(
self,
element_filter: Dict[str, Any],
param_name: str,
snapshot_id: str = "",
include_readonly: bool = False,
workspace: Any = None,
**_,
) -> Dict[str, Any]:
elements = self._get_elements(snapshot_id, workspace)
matched = [el for el in elements if _match_element(el, element_filter)]
rows = []
for el in matched:
params = el.get("params", {})
pinfo = params.get(param_name)
if pinfo is None:
continue
if not include_readonly and pinfo.get("readonly", False):
continue
rows.append({
"uid": el["uid"],
"element_id": el.get("element_id"),
"category": el.get("category"),
"type_name": el.get("type_name"),
"param_name": param_name,
"value": pinfo.get("v"),
"storage": pinfo.get("storage"),
"readonly": pinfo.get("readonly", False),
"instance": pinfo.get("instance", True),
})
return {
"param_name": param_name,
"element_count": len(matched),
"rows_with_param": len(rows),
"rows": rows,
}
def diff_params(
self,
snapshot_a_id: str,
snapshot_b_id: str,
param_names: List[str],
workspace: Any = None,
**_,
) -> Dict[str, Any]:
snap_a = _load_snapshot(snapshot_a_id, workspace)
snap_b = _load_snapshot(snapshot_b_id, workspace)
els_a = {el["uid"]: el for el in snap_a.get("elements", [])}
els_b = {el["uid"]: el for el in snap_b.get("elements", [])}
diffs = []
for uid, el_b in els_b.items():
el_a = els_a.get(uid)
if not el_a:
continue
for pname in param_names:
pinfo_a = el_a.get("params", {}).get(pname)
pinfo_b = el_b.get("params", {}).get(pname)
val_a = pinfo_a.get("v") if pinfo_a else None
val_b = pinfo_b.get("v") if pinfo_b else None
if val_a != val_b:
diffs.append({
"uid": uid,
"param_name": pname,
"before": val_a,
"after": val_b,
})
return {
"snapshot_a_id": snapshot_a_id,
"snapshot_b_id": snapshot_b_id,
"param_names": param_names,
"diffs_count": len(diffs),
"diffs": diffs,
}
def plan_set_params(
self,
element_filter: Dict[str, Any],
param_updates: Dict[str, Any],
snapshot_id: str = "",
workspace: Any = None,
**_,
) -> Dict[str, Any]:
elements = self._get_elements(snapshot_id, workspace)
matched = [el for el in elements if _match_element(el, element_filter)]
planned = []
blocked = []
for el in matched:
# Simulate worksharing skip if workset is set (real Revit would check ownership)
workset = el.get("workset")
if workset:
# Just a warning, not a hard block without live Revit connection
logger.debug(f"Element {el['uid']} is on workset '{workset}' — check ownership in Revit.")
el_updates = {}
el_blocked = []
for pname, new_val in param_updates.items():
ok, reason = _validate_param_update(el, pname, new_val)
if ok:
# Record before-value for rollback
pinfo = el.get("params", {}).get(pname, {})
el_updates[pname] = {
"before": pinfo.get("v"),
"after": new_val,
"storage": pinfo.get("storage"),
}
else:
el_blocked.append({
"uid": el.get("uid"),
"element_id": el.get("element_id"),
"param": pname,
"reason": reason,
})
if el_updates:
planned.append({
"uid": el["uid"],
"element_id": el.get("element_id"),
"updates": el_updates,
})
if el_blocked:
blocked.extend(el_blocked)
preview = {
"element_count": len(matched),
"planned_count": len(planned),
"blocked_count": len(blocked),
"blocked": blocked,
"description": (
f"Set {list(param_updates.keys())} on {len(planned)} element(s). "
f"{len(blocked)} validation issue(s) blocked."
),
}
return _make_action_plan(
"plan_set_params",
{"element_filter": element_filter, "param_updates": param_updates, "snapshot_id": snapshot_id},
{**preview, "planned": planned},
)
def export_params_csv(
self,
element_filter: Dict[str, Any],
param_names: List[str],
snapshot_id: str = "",
output_filename: str = "params_export.csv",
workspace: Any = None,
**_,
) -> Dict[str, Any]:
elements = self._get_elements(snapshot_id, workspace)
matched = [el for el in elements if _match_element(el, element_filter)]
output_path = _confined(workspace, output_filename)
header = ["uid", "element_id", "category", "family", "type_name"] + param_names
with open(output_path, "w", newline="", encoding="utf-8") as csvfile:
writer = csv.DictWriter(csvfile, fieldnames=header, extrasaction="ignore")
writer.writeheader()
for el in matched:
row = {
"uid": el["uid"],
"element_id": el.get("element_id", ""),
"category": el.get("category", ""),
"family": el.get("family", ""),
"type_name": el.get("type_name", ""),
}
for pname in param_names:
pinfo = el.get("params", {}).get(pname)
row[pname] = pinfo.get("v") if pinfo else ""
writer.writerow(row)
return {
"status": "exported",
"output_file": str(output_path),
"element_count": len(matched),
"param_names": param_names,
}
def import_params_csv(
self,
csv_filename: str,
snapshot_id: str = "",
workspace: Any = None,
**_,
) -> Dict[str, Any]:
csv_path = _confined(workspace, csv_filename)
if not csv_path.exists():
raise ValueError(f"CSV file '{csv_filename}' not found in workspace.")
elements = self._get_elements(snapshot_id, workspace)
els_by_uid = {el["uid"]: el for el in elements}
planned = []
blocked = []
with open(csv_path, "r", encoding="utf-8") as f:
reader = csv.DictReader(f)
reserved_cols = {"uid", "element_id", "category", "family", "type_name"}
for row in reader:
uid = row.get("uid", "").strip()
if not uid:
continue
el = els_by_uid.get(uid)
if not el:
blocked.append({"uid": uid, "reason": "Element not found in snapshot."})
continue
el_updates = {}
for pname, val_str in row.items():
if pname in reserved_cols or not pname:
continue
# Try cast to appropriate type via current param storage
pinfo = el.get("params", {}).get(pname)
storage = pinfo.get("storage") if pinfo else "String"
# Cast value
try:
if storage == "Double":
new_val = float(val_str)
elif storage == "Integer":
new_val = int(val_str)
elif storage == "Boolean":
new_val = val_str.lower() in ("true", "1", "yes")
else:
new_val = val_str
except (ValueError, TypeError):
blocked.append({"uid": uid, "param": pname, "reason": f"Cannot cast '{val_str}' to {storage}"})
continue
ok, reason = _validate_param_update(el, pname, new_val)
if ok:
el_updates[pname] = {
"before": pinfo.get("v") if pinfo else None,
"after": new_val,
}
else:
blocked.append({"uid": uid, "param": pname, "reason": reason})
if el_updates:
planned.append({"uid": uid, "element_id": el.get("element_id"), "updates": el_updates})
preview = {
"csv_filename": csv_filename,
"planned_count": len(planned),
"blocked_count": len(blocked),
"blocked": blocked,
}
return _make_action_plan("import_params_csv", {"csv_filename": csv_filename}, {**preview, "planned": planned})
# -----------------------------------------------------------------------
# Internal helpers
# -----------------------------------------------------------------------
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, 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)
return data.get("elements", [])