Skip to content

Releases

Release v0.1.1 - Enforce dry_run purity

Choose a tag to compare

@omocaig1986 omocaig1986 released this 22 May 13:15

[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_run in static_checks.py:
    refuses any write-mode handler that performs a non-transactional
    external write before the if dry_run: guard. Catches Groups.Create,
    Definitions.Create, open(...,'w'), File.WriteAllText and 1-hop
    indirect helper calls (the exact pattern of the reported bug).
  • New template shared-parameter.py.tmpl with 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.md to 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.tmpl refactored 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.md hard rules extended from 5 to 7: added "no return
    inside with transaction_safe" and "no write before if dry_run:".
  • thread_helpers.py docstring rewritten with direct citations
    from the pyRevit source (server.py:38, :104) proving that pyRevit
    Routes already dispatches @api.route handlers on the UI main thread
    via UI.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 with dry_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

Choose a tag to compare

@omocaig1986 omocaig1986 released this 22 May 08:02

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 RevitMcpRoutes with HTTP endpoints /_health, /_validate, /_reload, /tools/<name>.
  • Python MCP server revit-mcp-server that proxies between Claude (Code or Desktop) and pyRevit. Hot-reload via notifications/tools/list_changed.
  • Skill revit-mcp-tool-generator for 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.bat for complete rollback that doesn't touch external dependencies (Python/Revit/pyRevit/Claude).
  • Export/import scripts export-tool.ps1 + import-tool.ps1 for sharing generated tools as .tool.zip bundles.
  • Portable skill dist/system-prompt.md for 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.md at 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).