Repository navigation
Releases
Releases · studioliquid-lab/revit-mcp-tool-generator
Release v0.1.1 - Enforce dry_run purity
[0.1.1] — 2026-05-22
Hardening release based on the first field bug report from an in-house user.
A generated create_shared_parameter tool was causing deferred Access
Violation crashes in Revit. Root cause investigation revealed two issues
the skill was not preventing: (a) a misunderstanding about the
@run_on_ui_thread decorator being "no-op", which is correct but was
inadequately documented; (b) a structural gap in the template
write-with-preview.py.tmpl that allowed non-transactional writes
(SP file mutation) before the dry_run guard, silently violating
dry-run purity.
Added
- Static check
write-before-dry_runinstatic_checks.py:
refuses any write-mode handler that performs a non-transactional
external write before theif dry_run:guard. CatchesGroups.Create,
Definitions.Create,open(...,'w'),File.WriteAllTextand 1-hop
indirect helper calls (the exact pattern of the reported bug). - New template
shared-parameter.py.tmplwith the canonical 5-phase
pattern for Shared Parameter tools (validation → pure read → dry_run
exit → file SP write → transactional BindingMap mutation). - Cookbook §16 "Access Violation: root causes (and what is NOT one)"
— debunks the two common false leads (no-op decorator misread, static
API reads off-thread) and ranks the 5 real causes with code examples. - Cookbook §17 "Shared Parameters: the only correct pattern" — full
canonical flow with 5 explicit guarantees and the exact anti-pattern. - Template decision tree in
SKILL.mdto guide template choice
(read-simple / read-on-selection / write-with-transaction /
write-with-preview / shared-parameter). - 14 new pytest tests (7 for the new static check, 7 loop-closure
tests that verify every template still passes the checks it teaches).
Changed
- Template
write-with-preview.py.tmplrefactored from a single
{{PRE_TX_LOGIC}}placeholder to three phase-separated placeholders:
{{PURE_READ_LOGIC}},{{APPLY_NON_TX_LOGIC}},{{TX_LOGIC}}.
This structural change makes it impossible for a generator to put
a non-transactional write before the dry_run guard by accident. SKILL.mdhard rules extended from 5 to 7: added "noreturn
insidewith transaction_safe" and "no write beforeif dry_run:".thread_helpers.pydocstring rewritten with direct citations
from the pyRevit source (server.py:38, :104) proving that pyRevit
Routes already dispatches@api.routehandlers on the UI main thread
viaUI.ExternalEvent.Raise(). The decorator is intentionally a no-op
marker, and the docstring now makes this unambiguous.
Fixed
- dry_run purity for tools that touch external files (Shared
Parameters file, CSV exports). Pre-0.1.1, a tool could silently
mutate the SP file even when called withdry_run=true. From 0.1.1
the static validator refuses such tools at install time.
Testing
- Test suite: 63 passing (up from 49 in v0.1.0). +14 new tests.
v0.1.0 — first MVP
Changelog
🇬🇧 English · 🇮🇹 Italiano
All notable releases of this project will be documented here.
Format follows Keep a Changelog and versioning follows SemVer.
Unreleased
No changes yet.
0.1.0 — 2026-05-13
First public release.
Added
- pyRevit extension
RevitMcpRouteswith HTTP endpoints/_health,/_validate,/_reload,/tools/<name>. - Python MCP server
revit-mcp-serverthat proxies between Claude (Code or Desktop) and pyRevit. Hot-reload vianotifications/tools/list_changed. - Skill
revit-mcp-tool-generatorfor Claude Code: given a natural-language prompt, generates pyRevit handler + MCP manifest, validates, installs, tests. - Templates for 4 tool categories:
read-simple,read-on-selection,write-with-transaction,write-with-preview(the last with mandatory dry-run for dangerous operations). - Cookbook with 15 tested pyRevit patterns for the most common cases (collectors, parameter access, transactions, etc.).
- Revit API quick-reference with the most-used classes.
- Gotcha list of 10 known IronPython 2.7 pitfalls (PEP 263,
Element.Name, etc.). - Automatic setup via
setup.bat(double-click): verifies prerequisites, configures pyRevit, installs MCP server, registers in Claude Code + Claude Desktop. - Uninstaller
uninstall.batfor complete rollback that doesn't touch external dependencies (Python/Revit/pyRevit/Claude). - Export/import scripts
export-tool.ps1+import-tool.ps1for sharing generated tools as.tool.zipbundles. - Portable skill
dist/system-prompt.mdfor non-Claude-Code agents (ChatGPT, Cursor, Cline, etc.). - 49 pytest tests on the backend (pure-python pyRevit extension + MCP server).
- User documentation in
docs/user/+INSTALL.mdat the root.
Security
- Import whitelist in generated tools (forbids
os,subprocess,socket,requests,eval,exec). - Mandatory dry-run for dangerous operations (deletion, modification of > 10 elements, modification of types/families/levels).
- Static validation (PEP 263, thread marker, transaction marker) before installing a tool.
- Managed Revit transactions with a context manager that performs automatic rollback on exception.
Known limitations
- Tested ONLY on Revit 2024 with pyRevit Master. Other versions (2022, 2023, 2025+) may work but are not guaranteed. Open an Issue to share results on different versions.
- Hot-reload in Claude Desktop App is not reliable (Desktop App MCP client limitation). Workaround: close and reopen the app after creating a new tool. Claude Code CLI works perfectly.
- Windows only (Revit is Windows only).
- Revit version fixed at setup (single-version-at-a-time).