nwd-mcp

<!-- mcp-name: io.github.bimwright/nwd-mcp --> <p align="center"> <img src="https://raw.githubusercontent.com/bimwright/.github/master/assets/logos/nwd-mcp.png" alt="nwd-mcp" width="180" /> </p> <h1 align="center">nwd-mcp</h1> <p align="center"> <a href="https://github.com/bimwright/nwd-mcp/actions/workflows/build.yml"><img src="https://github.com/bimwright/nwd-mcp/actions/workflows/build.yml/badge.svg" alt="build" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license" /></a> <a href="#capabilities--architecture"><img src="https://img.shields.io/badge/Navisworks-2022--2027-2D9B9B" alt="Navisworks 2022-2027" /></a> <a href="#tool-surface"><img src="https://img.shields.io/badge/MCP-33%20tools-6C47FF" alt="MCP tools" /></a> </p> <p align="center"> English · <a href="README.vi.md">Tiếng Việt</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> </p>

nwd-mcp is a professional-grade Model Context Protocol (MCP) gateway for Autodesk Navisworks Manage automation. It enables AI agents to query, inspect, navigate, and script Autodesk Navisworks Manage desktop sessions locally over stdin/stdout.

---

Capabilities & Architecture

• Supported Host: Autodesk Navisworks Manage only. (Freedom and Simulate are not supported).
• Supported Versions: 2022, 2023, 2024, 2025, 2026, and 2027.
• Two-Process Model: Lightweight .NET 8 console server communicating with a version-specific in-process plug-in. Wire transport is TCP NDJSON over loopback for every supported year (2022–2027); all six plug-in shells target .NET Framework 4.8 / net48. (Unlike the rest of the bimwright family, nwd-mcp does not use Named Pipe transport — the loopback-TCP convention applies uniformly across all versions.)
• Security First: Per-session random cryptographic token validation, loopback-only binding for the TCP transport, and absolute file path sanitization in error messages returned to the model.
• Multi-Instance Routing: Automatically detects multiple running Navisworks Manage instances and supports switching targets dynamically.

Navisworks shows one activity card for MCP commands. Toasts are on by default and stay up for 20 seconds after the latest result (10, 20, 30, or 60). Hover pauses the card; leaving it starts the selected interval again. A deliberate hover smoothly expands a compact three-row view of the current card's individually bordered outcomes (tool, result, success/failure and local completion time in 24-hour HH:mm:ss). Every outcome in that card is retained, oldest above newest; the view starts at the latest three, and scrolling up reaches earlier calls through a thin RVT-style scrollbar. Leaving smoothly collapses it. Incoming outcomes appear immediately: at the bottom, the view follows the newest calls; while reading older calls, it preserves your scroll position. Returning to the bottom resumes following. The preview works with branding off and respects reduced motion. These length-limited summaries live only in memory and are discarded when the card closes or resets; they do not enable Record or retain raw requests, response JSON or script source. The BIMwright wordmark stays off unless Show branding is turned on. nwd_health_check does not appear on the card. The Bimwright ribbon tab has Toasts, Toast Brand, Record, and Status. Record is off until you turn it on; it then appends every tool call to %LOCALAPPDATA%\Bimwright\nwd-mcp\mcp-calls.jsonl. send_code is stored as a length and SHA-256, not the script. Settings live in %LOCALAPPDATA%\Bimwright\nwd-mcp\nwdmcp.config.json. BIMWRIGHT_NWD_ENABLE_TOAST and BIMWRIGHT_NWD_RECORD_CALLS override those switches at the next launch.

Status → toast position: choose horizontal Left/Right and vertical Top/Bottom independently (default: top-left). Changes apply and save immediately; changing the corner clears any saved drag offset. Enable Allow dragging the toast to drag its title row; a normal click still dismisses the card. Disabling drag returns to the selected corner without deleting the saved position; re-enabling restores it. Reset position removes the offset. Positions are stored relative to the Navisworks window in DIP and clamped to its monitor's work area. Bottom anchors expand upward; if space is insufficient, expansion uses the opposite side. Motion respects the Windows animation setting. A save failure is reported inline in Status while the new preference remains active for this session. Latest-tool and outcome tooltips include the sanitized result, status, completion time and measured duration when available. This does not coordinate overlapping toasts from different apps.

---

Current Status

| Component | Status | |---|---| | MCP gateway server (.NET 8) | ✅ Builds warning-clean (Debug + Release) | | Unit tests (155 xUnit) | ✅ All passing | | Plug-in handler implementations | ✅ Verified against a live Navisworks Manage session | | Plug-in projects (net48) | ✅ Compile against the Navisworks Manage SDK |

Note: The plug-in handler layer uses real Navisworks .NET API calls (not stubs or fabricated data) and has been exercised against a live Navisworks Manage instance. The first-run checklist is docs/testing/manual-smoke.md.

---

Install

Download the client setup ZIP from GitHub Releases. It includes a self-contained MCP server and the Navisworks Manage plugin years compiled for that release (see manifest.json). The v1.0.0 ZIP ships 2025 only. Other years: build from source against that year’s Manage SDK.

$tag = (Invoke-RestMethod https://api.github.com/repos/bimwright/nwd-mcp/releases/latest).tag_name
$zip = "$env:TEMP\NwdMcp.Setup-$tag-win-x64.zip"
$dir = "$env:TEMP\NwdMcp.Setup-$tag-win-x64"
Invoke-WebRequest "https://github.com/bimwright/nwd-mcp/releases/download/$tag/NwdMcp.Setup-$tag-win-x64.zip" -OutFile $zip
Expand-Archive $zip -DestinationPath $dir -Force

powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -WhatIf
powershell -ExecutionPolicy Bypass -File "$dir\install.ps1"

Deploys %APPDATA%\Autodesk\ApplicationPlugins\Bimwright.Nwd.bundle\ and nwd-mcp.exe at the fixed path %LOCALAPPDATA%\Bimwright\nwd-mcp\server\current\. Restart Navisworks Manage. Point your MCP client at that nwd-mcp.exe path. Pin a year with --target 2025 or BIMWRIGHT_NWD_TARGET=2025 when multiple instances may run.

The NuGet package Bimwright.Nwd.Server is server-only: it has no Navisworks plug-in. Install from the setup ZIP; use dotnet tool install -g Bimwright.Nwd.Server only if the plug-in is already installed from the ZIP and you want the server as a global .NET tool (command bimwright-nwd).

Developer: dotnet build a plugin-navisNN project, then pwsh scripts\install-bundle.ps1 -Year 2025 -Configuration Release.

Useful flags after wiring: --read-only / BIMWRIGHT_NWD_READ_ONLY=1.

---

Tool Surface

A default launch registers every toolset: 33 tools. --read-only leaves 21. Every tool uses the nwd_* prefix.

1. Target/Meta Tools (3)

• nwd_list_available_targets — List all active discovered Navisworks sessions.
• nwd_get_current_target — Report which session the server is currently pointed at.
• nwd_switch_target — Point the gateway at a different active session.

2. File Tools (3)

• nwd_list_recent_files — List recent files for the running Manage year, in File menu order.
• nwd_open_file (Write) — Open a file. Refuses while the current file has unsaved changes unless discard_changes is true.
• nwd_import_model (Write) — Bring a model into the open document. append (default) adds it; merge combines it.

3. Query/Read Tools (8)

• nwd_health_check — Probe host/document state and loaded server/plugin versions, build ids and alignment. Offline by default; optional check_updates=true compares both components with the latest official stable release and tag revision. No host still returns server identity with ok:false, host_connected:false.
• nwd_get_document_info — Retrieve active document name, file path, and model count.
• nwd_get_model_statistics — Retrieve counts of elements, models, and selections.
• nwd_get_model_tree — Retrieve a bounded model tree node hierarchy.
• nwd_get_item_properties — Retrieve property categories and property lists for an element.
• nwd_batch_get_properties — Retrieve properties for multiple elements at once.
• nwd_find_items — Query elements using advanced property/category filters.
• nwd_find_items_by_name — Search elements by display name.

4. Selection Tools (3)

• nwd_get_current_selection — Retrieve element IDs of the active user selection.
• nwd_clear_selection (Write) — Clear the active selection.
• nwd_select_items_by_search (Write) — Select items matching property/name filters.

5. Selection Sets Tools (3)

• nwd_list_sets — Retrieve selection and search sets, recursing folders.
• nwd_get_selection_set_items — Retrieve elements inside a set.
• nwd_execute_search_set (Mixed) — Execute a search set; optionally select matches.

6. Viewpoint/Navigation Tools (4)

• nwd_list_viewpoints — Enumerate saved viewpoints and folders.
• nwd_get_current_viewpoint — Retrieve current camera and view state.
• nwd_goto_viewpoint (Write) — Navigate the viewport camera to a saved viewpoint.
• nwd_save_viewpoint (Write) — Save the active view as a named viewpoint.

7. Visibility Tools (2)

• nwd_hide_items (Write) — Hide/show specified elements.
• nwd_unhide_all (Write) — Reset all hidden elements to visible.

8. Escape Hatch Scripting (1)

• nwd_send_code (Write) — Run a C# script on the Navisworks UI thread with doc as the active document. Returns the last expression as result and Console output as stdout; Navisworks waits while it runs.

9. ToolBaker Governed Tools (6)

• nwd_list_baked_tools — List all verified compiled reusable tools.
• nwd_run_baked_tool (Write) — Run an accepted baked tool by name with parameters.
• nwd_list_bake_suggestions — List adaptive workflow suggestions.
• nwd_accept_bake_suggestion (Write) — Validate, compile, and deploy a suggested tool.
• nwd_dismiss_bake_suggestion (Write) — Dismiss/snooze an active suggestion.
• nwd_create_bake_issue_draft — Generate a draft GitHub issue for requested tools.

---

Runtime health and updates

Start each Navisworks session with one nwd_health_check(check_updates=true) call after selecting the target, so the agent discovers newer stable releases. If network access is unavailable or disallowed, use the offline default and leave update status not checked/unknown. Later routine probes stay offline. setup_gateway/setup_plugin describe loaded assemblies; their SHA-256 observes the disk file at capture time, not loaded memory. Version/revision alignment is not proof of compatibility or publisher trust. Legacy plugins without identity report unknown version/build evidence. The host probe uses the UI thread and can time out while Navisworks is busy.

check_updates=true uses one official release baseline and a shared 5-second network budget. Inspect both update.components.server and .plugin: matching versions alone are insufficient, and unavailable evidence remains unknown. checked confirms release lookup, not that both components are current. Per-component update_available compares semantic versions; the overall flag is false only when both versions/revisions match, true when a newer stable version exists for either component, and null otherwise. Source-revision comparison does not verify artifact bytes.

Inspect update.notification and follow agent_action. Codes distinguish NEW_RELEASE_AVAILABLE, RELEASE_REVIEW_REQUIRED, RELEASE_IDENTITY_UNVERIFIED,