RvtMcp changelog

version

0.6.2 → 1.2.0

https://raw.githubusercontent.com/bimwright/rvt-mcp/HEAD/AGENTS.md

− This file is machine-readable install instructions for AI coding agents (Claude Code, Cursor, Cline, VS Code Copilot, Gemini CLI, Antigravity, OpenCode, Codex, and any other stdio MCP client). A user pointed you here because they want rvt-mcp (a Revit MCP server) wired up without hand-editing config files themselves.− - Connect MCP clients: the installer wires every detected client by default (`-Client <names>` limits it, `-Client none` skips it). Your own client — the one this session runs in — must end up wired.− - Verify the handshake and roll back on failure.− **Current status — 2026-09-27:** latest published release is **v0.8.1**. Use `/repos/bimwright/rvt-mcp/releases/latest`. Do not install `v0.5.0` or earlier tags.− - Install from unpublished/old tags or old `RvtMcp.Setup-*.zip` URLs for v0.5.0 and earlier.− 2. **Install from the latest GitHub Release ZIP only** for a Revit client machine. Do not fall back to `dotnet tool install`, v0.5.0 or earlier tags, source build, or repo clone unless the user explicitly asks for developer installation. If they explicitly asked for the NuGet global tool: `RvtMcp.Server` 0.6.1+, never `Bimwright.Rvt.Server`, and they still need the ZIP for plugins.− 5. **On any failure, verify rollback.** The installer restores the previous add-ins and server on any caught error and reports retained `.rvtmcp-rollback-*` backups if recovery fails. Client-config edits made by `-Client` are backed up to `<config>.bak` and verified by reparse — a failed write restores the backup on the spot. For hand edits, back up the client config yourself first. Do not use full uninstall as an upgrade rollback: upgrades replace add-ins and server in place. Personal data is o− 6. **Verify before claiming done.** After connecting a client, run `tools/list` in it and confirm the single `rvt-mcp` entry responds, then call `revit_get_current_view_info` with no args.− If the user explicitly says "skip the prompts, just install" — still do gate 1 (preview) and gate 5 (verify), but collapse gates 2 and 3 into a single upfront approval. **Never silently skip preview or verify.**− | Windows | `[System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform('Windows')` | Stop — Revit is Windows-only. |− | Revit 2022–2027 | `Get-ChildItem 'HKLM:\SOFTWARE\Autodesk\Revit\' -ErrorAction SilentlyContinue` | Tell the user to install Revit. You cannot. |− If Revit is not running when the user first tries a tool call, that's fine — the server only needs Revit alive at tool-call time, not at install time.− Invoke-WebRequest "https://github.com/bimwright/rvt-mcp/releases/download/$tag/RvtMcp.Setup-$tag-win-x64.zip" -OutFile $zip− If `/releases/latest` 404s, the tag is older than v0.6.1, or the setup asset is missing, stop. Do not clone, build, or install the .NET SDK for a client machine. Do not install v0.5.0 or earlier ZIPs.− powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -WhatIf− powershell -ExecutionPolicy Bypass -File "$dir\install.ps1"− - seeds `%LOCALAPPDATA%\RvtMcp\rvtmcp.config.json` with `"toolsets": ["all"]` so a fresh install exposes the full tool surface — a `toolsets` key the user already set is kept, and the file stays user data (uninstall keeps it, `-Purge` removes it);− Any error restores the previous add-ins and server. A machine-wide copy under `%ProgramData%` stops the install before anything changes (removing it needs admin rights). The same run then wires every detected MCP client — that is Step 3.− - `Server :` is the command for Step 3. Since the fixed-path installer this is `%LOCALAPPDATA%\RvtMcp\rvt\server\current\rvt-mcp.exe`; v0.6.2 and earlier printed a versioned folder.− - `Legacy :` lists versioned copies from older installers. Repoint clients (Step 3), then run `install.ps1 -PruneOldServers`.− **Updates.** Close Revit, then run the new ZIP's installer the same way, without uninstalling first. The server path stays the same, so MCP clients only need a restart.− ## Step 3 — Connect the MCP client− The Step 2 run already did this: by default the installer wires every detected client with the wiring guide — detection, `.bak` backup, minimal text edits (JSONC comments survive), repointing old versioned paths, reporting custom launchers and legacy `bimwright-rvt*` entries, and never duplicating an existing `rvt-mcp` entry. To limit or skip it:− ```powershell− powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -Client cursor,claude   # only these clients− powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -Client none            # leave client configs alone− ```− `Client  :` lines in the summary report what happened per client (wired / already / repointed / custom launcher kept / not detected). Cherry Studio has no safe file path — the installer prints a `cherrystudio://` deeplink for the user to open instead.− **Your own client comes first.** The client this session runs in is the one the user is talking to, so it must end up with the `rvt-mcp` entry. Find its `Client :` line in the summary. If it reads `not detected`, `skipped`, `custom` or is missing, wire it yourself now (`-Client <your client>`, or your client's own `mcp add`) before you report anything. Its tools only appear after a restart, which ends this session — so make that the last step: tell the user to restart you and verify `tools/list`− | Command | The `Server :` path from the install summary, as an absolute path — normally `C:\Users\<user>\AppData\Local\RvtMcp\rvt\server\current\rvt-mcp.exe` |−       "command": "C:\\Users\\<user>\\AppData\\Local\\RvtMcp\\rvt\\server\\current\\rvt-mcp.exe",− - **Which clients:** by default the installer wires every client it detects; if the user wants only some, pass `-Client <names>` (or `-Client none`). For hand wiring, prefer the client's own CLI over editing files, and show the exact command or diff before applying it (gate 2). Register the server where every project sees it — for example the user scope, not one project folder — unless the user asks otherwise.−   - An entry pointing at `...\RvtMcp\rvt\server\<version>\rvt-mcp.exe` (older installers) should be repointed to the `current` path. Afterwards `install.ps1 -PruneOldServers` removes the old copies.− ## Step 4 — Verify− 1. **List tools.** Ask the host to call `tools/list` against the wired server. Installed servers seed `toolsets=all`, so expect the full surface including `revit_get_current_view_info`, `revit_batch_execute`, `revit_send_code_to_revit` and clash/export/MEP tools. If the user removed the seeded key or set their own list, the bare default is `query,create,view,meta` — check `rvtmcp.config.json` and the client entry's `args`.− 2. **Handshake call.** With Revit 2022–2027 running and a model open, call `revit_get_current_view_info` with no args. A valid response looks like:−     ```json−     {−       "view_name": "Level 1",−       "view_type": "FloorPlan",+ This file is the install protocol for an AI agent with permission to run PowerShell and edit files on the user's Windows machine (for example Claude Code, Codex or Cursor). A normal chat session without local execution tools cannot perform the install: explain that limitation and offer the manual steps instead.+ **Installer agent ≠ target client.** The user may ask Codex to install for Claude Desktop. Configure only the client(s) the user requests, not automatically the client running your session. If no target is specified, ask before previewing changes.+ - Connect the requested MCP client(s): always pass `-Client <names>` for direct registration, or `-Client none` for the Claude Desktop MCPB route. The installer itself defaults to every detected client; do not use that default unless the user requested it.+ - Verify installation, target-client connection and Revit handshake separately; troubleshoot failures and verify any attempted rollback.+ **Release selection:** resolve `/repos/bimwright/rvt-mcp/releases/latest` once for a normal install, or use the published release the user explicitly requested. Record its tag and use assets from that one release throughout. v1.0.0 introduced the Claude Desktop MCPB route and the `%LOCALAPPDATA%\Bimwright\rvt-mcp\` data path. Do not install `v0.5.0` or earlier tags.+ - Install from unpublished tags or `RvtMcp.Setup-*.zip` URLs for v0.5.0 and earlier.+ 2. **Install from the selected published GitHub Release ZIP only** for a Revit client machine. Do not fall back to `dotnet tool install`, v0.5.0 or earlier tags, source build, or repo clone unless the user explicitly asks for developer installation. If they explicitly asked for the NuGet global tool: `RvtMcp.Server` 0.6.1+, never `Bimwright.Rvt.Server`, and they still need the ZIP for plugins.+ 5. **On a caught install/edit failure, verify recovery.** The installer attempts to restore the previous add-ins and server on a caught installation error and reports retained `.rvtmcp-rollback-*` backups if recovery fails. A pending restart, missing model or stopped Revit connection is not an installation rollback trigger. Client-config edits made by `-Client` are backed up to `<config>.bak` and verified by reparse — a failed write restores the backup on the spot. For hand edits, back up the cl+ 6. **Verify before claiming done.** Report installation, target-client connection and Revit handshake separately (Step 4). When the target client's tools are unavailable to this session, leave connection/handshake **pending user verification**; never use your own client as proof for another client.+ If the user explicitly says "skip the prompts, just install", still preview changes and verify the result; combine the two approval gates into one upfront approval. **Never silently skip preview or verify.**+ | Windows | `$env:OS -eq 'Windows_NT'` | Stop — Revit is Windows-only. |+ | Revit 2022–2027 | Inspect `HKLM:\SOFTWARE\Autodesk\Revit\` and `%ProgramFiles%\Autodesk\Revit <year>\`; confirm an actual `Revit.exe` exists (registry keys may survive uninstall). The installer's `-WhatIf` performs detection. | Tell the user to install Revit. You cannot. |+ Revit may be closed during installation and tool discovery. Revit-dependent calls require it running, with MCP started and a model open for the view-info handshake.+ ## Step 0 — Confirm target, route and existing installation+ 1. Confirm the target client(s). Installer names: **`claude` = Claude Code**, **`claude-desktop` = Claude Desktop**. Do not substitute one for the other.+ 2. For Claude Desktop, default to **Setup + direct config registration** (`-Client claude-desktop`) for agent-assisted installs. If the user requests the extension/settings UI, choose **Setup + MCPB** (`-Client none`). Use exactly one Desktop registration; do not install both routes.+ 3. Read [docs/mcp-client-wiring.md](docs/mcp-client-wiring.md), especially the Claude Desktop section. Detect classic versus MSIX and inspect the active config and any existing rvt-mcp extension in Desktop's UI. If you cannot inspect the UI, ask the user whether the extension is installed. Do not guess the config path or silently remove an existing registration. With an existing MCPB, retain that route unless the user approves switching.+ 4. Check `%LOCALAPPDATA%\RvtMcp\` (legacy) and `%LOCALAPPDATA%\Bimwright\rvt-mcp\` (current). For upgrades, close Revit and stop clients using the old gateway before installing. If both folders exist, stop and inspect/back up the data; do not delete either or merge them blindly. See [docs/install.md](docs/install.md#upgrade).+ 5. Ask the user to close Revit and fully quit Claude Desktop (tray included) before Desktop config edits. If Desktop is hosting this agent, finish preparation first and hand off the quit/install/relaunch step to the user or an agent outside Desktop. Do not kill processes or elevate automatically.+ For a normal latest-release install:+ $base = "https://github.com/bimwright/rvt-mcp/releases/download/$tag"+ Invoke-WebRequest "$base/RvtMcp.Setup-$tag-win-x64.zip" -OutFile $zip+ Invoke-WebRequest "$base/RvtMcp.Setup-$tag-win-x64.zip.sha256" -OutFile "$zip.sha256"+ $expected = ((Get-Content "$zip.sha256" -Raw).Trim() -split '\s+')[0]+ $actual = (Get-FileHash $zip -Algorithm SHA256).Hash+ if ($expected -notmatch '^[a-fA-F0-9]{64}$' -or $actual -ne $expected) { throw 'Setup ZIP checksum mismatch' }+ For an explicitly requested published release, set `$tag` to its tag instead of querying latest. Do not overwrite a previous extraction directory if it holds user files. If release lookup fails, the tag is older than v0.6.1, a required asset is missing or checksum verification fails, stop. Do not clone, build, or install the .NET SDK for a client machine. Do not install v0.5.0 or earlier ZIPs.+ For MCPB, also download the selected release's `rvt-mcp-desktop-<version>.mcpb` and matching `.mcpb.sha256` assets and verify the bundle hash before opening it (`<version>` is the selected tag without its leading `v`). If either asset is missing, stop; do not substitute an older bundle. Do not mix an extension from one release with a Setup ZIP from another.+ # Claude Desktop direct-config route (default for agent-assisted installs):+ powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -WhatIf -Client claude-desktop+ # Show the preview and obtain approval before running:+ powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -Client claude-desktop+ Use the **same options** for preview and apply. For another requested target, replace `claude-desktop` with its installer name; for MCPB use `none` in both commands. Pass a comma list only when the user requested multiple clients.+ - seeds `%LOCALAPPDATA%\Bimwright\rvt-mcp\rvtmcp.config.json` with `"toolsets": ["all"]` so a fresh install exposes the full tool surface — a `toolsets` key the user already set is kept, and the file stays user data (uninstall keeps it, `-Purge` removes it);+ A caught installation error triggers rollback of the previous add-ins and server; check the error for any retained recovery backups. A machine-wide copy under `%ProgramData%` stops the install before anything changes (removing it needs admin rights). The same run then wires the clients selected by `-Client` — that is Step 3.+ - `Server :` is the command for Step 3. Since the fixed-path installer this is `%LOCALAPPDATA%\Bimwright\rvt-mcp\server\current\rvt-mcp.exe`; v0.6.2 and earlier printed a versioned folder.+ - `Legacy :` lists versioned copies from older installers. Repoint clients (Step 3), then preview/apply `install.ps1 -PruneOldServers` with the same explicit `-Client` selection.+ **Updates.** Close Revit and stop clients using the gateway, then run the new ZIP's installer with the same explicit client selection, without uninstalling first. The server path stays the same; restart the clients afterwards. For MCPB, update the matching extension too.+ ## Step 3 — Connect the target MCP client+ ### Direct registration

Showing the first 40 of each.