NavisHelper

Navisworks Manage plugin and local MCP server for design engineers and BIM coordinators who need model search, selection, visibility, viewpoints, property export, and Clash Detective workflows.

What it does

Finds model items by name, property conditions, source file, hierarchy, or a global bounding-box zone, then selects the matches.
Shows, hides, isolates, frames, and colors model items with preview and confirmation controls for write operations.
Creates and manages selection sets, search sets, saved viewpoints, section-box viewpoints, and supported redline markups.
Exports selection properties and large model-subtree name lists to CSV, XLSX, or JSONL files.
Lists, groups, runs, renames, isolates, and reports Clash Detective tests and results.
Saves reviewed multi-step MCP workflows as reusable scenarios and resolves them back into ordinary tool calls.

Example prompts

“Find every item whose name contains pump, select the matches, and frame them in the active view.” (find_items, select_items, zoom_to_selection)
“Show me only the direct children of /100000-XXX1-YY-01; do not scan deeper levels.” (list_item_children)
“Export the current selection properties to D:\Exports\selection.xlsx; show me the dry-run first.” (selection_export_properties)
“Create a saved viewpoint named Pump room review from the current view.” (create_viewpoint)
“List the active clashes in test HVAC vs Structure, then isolate the first result.” (clash_list_results, clash_isolate_result; requires existing Clash Detective results)
“Preview a color scheme that makes _PI.rvm items blue and _EL.rvm items yellow, then wait for confirmation before applying it.” (model_color_scheme)
“Save the current selection as a static selection set named Review scope.” (create_selection_set)

Requirements

Requirement	Details
Operating system	Windows x64.
Autodesk application	Autodesk Navisworks Manage 2024, 2025, 2026, or 2027. Navisworks Simulate is not declared by the bundle.
Plugin runtime	.NET Framework 4.8.1, x64.
MCP server and configurator runtime	.NET 9. Framework-dependent packages require the .NET 9 runtime; self-contained packages can be produced by the repository publish script.
MCP client	An MCP client is required. The configurator has adapters for Claude Desktop, Claude Code, Codex, Cursor, OpenCode, and Kimi Code. Minimum client versions are not specified.
Build dependencies	Building the plugin requires Visual Studio/MSBuild, the .NET Framework 4.8.1 targeting pack, the .NET 9 SDK, and Autodesk Navisworks Manage SDK assemblies in `C:\Program Files\Autodesk\Navisworks Manage 20XX\`.
Declared package dependencies	MCP server: `Microsoft.Extensions.Hosting` 8.0.1 and `ModelContextProtocol` 1.2.0. Plugin: `Microsoft.Toolkit.Uwp.Notifications` 7.1.3, `Newtonsoft.Json` 13.0.3, Windows SDK Contracts 10.0.19041.1, `System.Runtime.WindowsRuntime` 4.6.0, `System.Runtime.WindowsRuntime.UI.Xaml` 4.6.0, `System.ValueTuple` 4.5.0, and reference-assembly packages.
Optional script dependencies	Python is used only by some smoke/check scripts, not by the MCP runtime. The minimum Python and PowerShell versions are not specified.
HTTP bridge port	None. The MCP client starts the server over stdio; the server connects to the Navisworks plugin through a local Windows named pipe.
LLM API access	Not required for the 100 registered MCP tools. The separate `AIColorObjects` plugin function requires a user-provided OpenRouter API key in `OPEN_ROUTER_NW_KEY`; API billing depends on the selected model.
AI data egress	`AIColorObjects` sends selected object names to the external OpenRouter API under the user’s key. Account for this when working with NDA-controlled models. The registered MCP tool path remains local.

Installation

The primary installation path is the per-user installer attached to a GitHub Release. It installs the Navisworks bundle, MCP server, and configurator without administrator rights, then offers to configure supported MCP clients.

Query the latest GitHub Release.

$release = Invoke-RestMethod -Uri "https://api.github.com/repos/mikhalchankasm/NavisWorksMaster/releases/latest"

Download the installer asset.

$asset = $release.assets | Where-Object { $_.name -like "NavisHelperSetup-*.exe" } | Select-Object -First 1
if (-not $asset) { throw "NavisHelper installer asset was not found in the latest release." }
$installer = Join-Path $env:TEMP $asset.name
Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $installer

Verify that Navisworks is closed.

if (Get-Process -Name Roamer -ErrorAction SilentlyContinue) { throw "Close Navisworks before installation." }

Run the installer.

Start-Process -FilePath $installer -Wait

Optionally verify client detection after the installer has configured the supported clients.

& "$env:LOCALAPPDATA\NavisHelper\McpConfigurator\NavisHelper.McpConfigurator.exe" --detect --mcp-server "$env:LOCALAPPDATA\NavisHelper\McpServer\NavisHelper.McpServer.exe"

Start the installed Navisworks Manage version.

$navisworksVersion = "2027"
Start-Process "$env:ProgramFiles\Autodesk\Navisworks Manage $navisworksVersion\Roamer.exe"

Configuration

The installer configures the supported clients automatically. Use a manual entry only when installing without the installer or configuring another JSON-based MCP client.

{
  "mcpServers": {
    "navishelper": {
      "command": "<path-to-install>\\NavisHelper.McpServer.exe",
      "args": []
    }
  }
}

This is a local stdio server configuration. Do not add a host, URL, or port. The server discovers running Navisworks plugin hosts and connects through a local named pipe named navishelper-mcp-<PID>.

Available tools

The current server registers 100 tools. Parameter types, required markers, and defaults below are taken from the recorded tools/list schemas.

Core model, selection, visibility, and viewpoints

Tool	Description	Parameters
`list_navisworks_hosts`	Lists running Navisworks MCP host instances. Use instance_id from this tool when multiple Navisworks windows are open, or navisworks_version when exactly one host of that version is running.	None.
`mcp_diagnostics`	Returns MCP diagnostics: JSONL log file path, discovery instances directory, and currently running Navisworks host records.	None.
`mcp_recent_calls`	Returns the last MCP JSONL call log lines. Use after failures or long runs to confirm which tools were invoked, their target Navisworks instance, elapsed time, status, and error code.	`lineCount: integer` [default=50]
`mcp_error_contract`	Returns the NavisHelper MCP error contract: stable error codes, meanings, retryability, and recommended client actions.	None.
`mcp_health_check`	Runs a read-only MCP/Navisworks health check and returns a verdict instead of throwing on partial failures. Use after long runs, timeouts, or suspected host hangs.	`rootItemLimit: integer` [default=10] `includeViewpointCheck: boolean` [default=true] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`active_model_context`	Returns a compact read-only context package for the active Navisworks model: host status, root model filenames, saved viewpoint/selection set counts, and recommended MCP workflow. Call this before searching a large model or when the user gives .rvm/.dwg names.	`rootItemLimit: integer` [default=100] `includeRootAliases: boolean` [default=false] `includeSavedItemsSummary: boolean` [default=true] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`find_items`	Finds Navisworks items by property conditions. Supports whole-model or subtree/current-selection scope, shallowest-match pruning, count-only estimates, and a clarification preflight. Old calls remain whole_model + matchDepth=all. Use preflight=true before ambiguous natural-language searches; for repeated inherited names prefer a narrow scope plus matchDepth=first.	`query: string` [default=""] `value: string` [default=""] `comparison: string` [default="contains"] `category: string` [default="Item"] `property: string` [default="Name"] searches: array<object{query:string/null, combineOperator:string/null, conditions:array/null}> [default=null] previewLimit: integer [default=10] scope: string [default=""] scopeHandle: string [default=""] scopeNodeName: string [default=""] scopeNodePath: string [default=""] matchDepth: string [default=""] countOnly: boolean [default=false] preflight: boolean [default=false] ignoreCase: boolean [default=true] ignoreDiacritics: boolean [default=false] ignoreCharWidth: boolean [default=false] instanceId: string [default=""] navisworksVersion: string [default=""]
`find_items_by_bbox`	Finds leaf model items whose axis-aligned bounding boxes intersect a global document-coordinate zone. Coordinates use the active Navisworks document units; this v1 tool does not transform local/grid coordinates. Read-only: it returns a match handle for select_items or visibility tools and never changes the selection.	`min: object{x:number, y:number, z:number}` [required] `max: object{x:number, y:number, z:number}` [required] `matchMode: string` [default="intersects"] `includeHidden: boolean` [default=true] `includeContainers: boolean` [default=false] `sourceFileContains: string` [default=""] `maxScannedItems: integer` [default=100000] `maxResults: integer` [default=5000] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`find_root_items_by_name`	Fast path for finding top-level/root Navisworks model items by displayed root name or Source File filename. Use this instead of find_items for long lists of appended .rvm/.dwg model file names. It returns the same match handles as find_items, so select_items, isolate_selected, and zoom_to_selection can be used afterward.	`names: array` [required] `comparison: string` [default="equals"] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`list_root_items`	Lists top-level/root Navisworks model items and appended model file names visible near the root of the selection tree. Use this before searching when you need the available .rvm/.dwg names.	`limit: integer` [default=1000] `includeAliases: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`list_item_children`	Lists the immediate children of one Navisworks model item by parentMatchHandle, fast exact parentPath, parentName, or sourceFile. Use this for direct subitems of a level/group such as '/100000-XXX1-YY-01'. It does not full-scan the model tree; for deep unknown nodes first call find_items and pass parentMatchHandle.	`parentMatchHandle: string` [default=""] `parentPath: string` [default=""] `parentName: string` [default=""] `sourceFile: string` [default=""] `comparison: string` [default="equals"] `includeHidden: boolean` [default=true] `limit: integer` [default=200] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`host_status`	Returns current Navisworks MCP host status: active document, process id, memory use, model count, and indexed root item count.	`instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`last_operation_status`	Returns host-side status for a recent request_id. Use after request_timeout, transport disconnect, or oversized-response suspicion to determine whether the Navisworks-side command eventually completed, failed, or is still running.	`requestId: string` [required] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_status`	Returns read-only status of the current Navisworks selection: selected item count and optional combined bounding box. Use before visibility or view operations to verify what is selected.	`includeBoundingBox: boolean` [default=true] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_copy_names`	Returns display names for the current Navisworks selection in copy-ready order. Use this when the user asks to copy, list, export, or summarize selected object names. Optional path/source fields help disambiguate repeated names.	`limit: integer` [default=10000] `includePaths: boolean` [default=false] `includeSourceFiles: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`dump_subtree_names`	Synchronously streams item names from one small root .rvm/.dwg subtree to a CSV or JSONL file. Hard-limited to avoid long Navisworks UI hangs; for large roots use start_subtree_names_dump plus dump_subtree_names_status.	`rootName: string` [required] `outputPath: string` [required] `format: string` [default="csv"] `sourceFile: string` [default=""] `includePath: boolean` [default=true] `includeSourceFile: boolean` [default=false] `includeHidden: boolean` [default=true] `overwrite: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`start_subtree_names_dump`	Starts a chunked CSV/JSONL dump job for all item names under one root .rvm/.dwg subtree. This returns quickly with jobId and instanceId and writes to outputPath.partial while running. Poll/cancel using the same instanceId. On success it atomically replaces outputPath; on failed/cancelled it removes the partial file.	`rootName: string` [required] `outputPath: string` [required] `format: string` [default="csv"] `sourceFile: string` [default=""] `includePath: boolean` [default=true] `includeSourceFile: boolean` [default=false] `includeHidden: boolean` [default=true] `overwrite: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`dump_subtree_names_status`	Advances and returns status for a subtree name dump job. Poll this until state is done/failed/cancelled using the same instanceId returned by start_subtree_names_dump. Each poll processes a bounded chunk on the Navisworks UI thread; keep maxElapsedMs near the 500 ms default when a user is actively working.	`jobId: string` [required] `maxItemsPerPoll: integer` [default=1000] `maxElapsedMs: integer` [default=500] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`cancel_subtree_names_dump`	Cancels a running subtree name dump job on the same instanceId returned by start_subtree_names_dump, closes its writer, clears queued ModelItem references, and removes its .partial file.	`jobId: string` [required] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selected_items_preview`	Returns a read-only preview of currently selected top-level Navisworks items: display name, class, path, source file, hidden state, child count, and optional per-item bounding boxes. It does not traverse descendants.	`limit: integer` [default=20] `includeBoundingBoxes: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selected_items_ancestry`	Returns currently selected Navisworks items with their structured parent chain from model root to each selected item. Use when the user asks for selected objects, their owners, parents, hierarchy, or structure up to the top; the response is suitable for exporting to text or JSON.	`limit: integer` [default=20] `includeBoundingBoxes: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selected_items_tree`	Returns the full current Navisworks selection as either a merged parent tree or a flat list. It reads Application.ActiveDocument.CurrentSelection without changing selection, supports more than 100 selected items, and includes selected counts/truncation flags.	`maxItems: integer` [default=10000] `maxDepth: integer/null` [default=null] `format: string` [default="tree"] `includeBoundingBoxes: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`item_properties_by_handle`	Returns a bounded read-only property preview for items referenced by match handles from find_items or find_root_items_by_name. Use categoryFilters to narrow large property sets. Defaults return up to 5 items per handle and 50 properties per item.	`matchHandles: array` [required] `itemLimit: integer` [default=5] `propertyLimit: integer` [default=50] `includeInternalNames: boolean` [default=false] `categoryFilters: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`current_viewpoint_info`	Returns read-only information about the current Navisworks viewpoint, including position, rotation, and common viewpoint properties when available.	`instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`list_saved_viewpoints`	Lists saved viewpoints and folders in the active Navisworks document without changing the current view. Returns name, path, type, depth, and child count.	`limit: integer` [default=200] `includeItemIds: boolean` [default=true] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`saved_viewpoints_export`	Exports the full Saved Viewpoints tree to CSV, JSON, or Markdown on the Navisworks host machine. Use before bulk rename/reorder work so duplicate names can be reviewed with current-tree itemId, path, parentPath, and index.	`outputPath: string` [required] `format: string` [default="csv"] `includeItemIds: boolean` [default=true] `overwrite: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`saved_viewpoints_import`	Imports standard Navisworks Saved Viewpoints XML by parsing view/viewfolder nodes and creating folders/viewpoints in the active document. Defaults to dry-run. Supports camera/folder import and simple rlellipse/rlline redlines; unsupported XML details such as other redline types, clip planes, hide/material overrides are reported as warnings.	`inputPath: string` [required] `targetFolderPath: string` [default=""] `preserveXmlFolders: boolean` [default=true] `previewLimit: integer` [default=200] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`saved_viewpoints_manage`	Creates/deletes/renames/moves Saved Viewpoints folders or viewpoints. delete_many removes up to 5000 explicitly listed viewpoints in one atomic plan. Defaults to dry-run; pass apply=true only after reviewing list_saved_viewpoints/export output. Supports duplicate names via current-tree itemId or occurrence.	`operation: string` [required] `pathOrName: string` [default=""] `itemId: string` [default=""] `occurrence: integer` [default=0] `name: string` [default=""] `newName: string` [default=""] `targetFolderPath: string` [default=""] `items: array<object{pathOrName:string/null, itemId:string/null, occurrence:integer/null}>` [default=null] `apply: boolean` [default=false] `allowDeleteNonEmptyFolder: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`saved_viewpoints_reorder`	Naturally sorts Saved Viewpoints folders/viewpoints so names containing numbers sort numerically (1, 2, 11). Defaults to dry-run. Can sort one folder or the full tree recursively.	`folderPath: string` [default=""] `itemId: string` [default=""] `recursive: boolean` [default=true] `foldersFirst: boolean` [default=true] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`list_selection_sets`	Lists selection/search sets and folders in the active Navisworks document without changing selection. Supports offset paging and path/name filtering. Returns duplicate-safe itemId, path, parentPath, type, index, explicit/static count, and dynamic-search flags.	`limit: integer` [default=200] `offset: integer` [default=0] `includeItemIds: boolean` [default=true] `pathPrefix: string` [default=""] `nameContains: string` [default=""] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`select_selection_set`	Selects an existing Navisworks Selection Set/Search Set by itemId, exact path, or unique name from list_selection_sets. Folder dry-runs return metadata without expanding child sets by default; folder apply requires allowFolderExpansion=true because large folders can be slow.	`pathOrName: string` [default=""] `itemId: string` [default=""] `occurrence: integer` [default=0] `allowFolderExpansion: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`create_search_set`	Creates a dynamic Navisworks Search Set and optionally saves it inside a Selection Sets folder. Defaults to dry-run. Conditions use the same schema as find_items; persistable operators are equals, contains, wildcard, and defined. Each condition supports logicalOperator=and\|or, negate, ignoreCase (default true), ignoreDiacritics, and ignoreCharWidth. Navisworks has no parentheses and AND binds more strongly than OR; express (A OR B) AND D as (A AND D) OR (B AND D) by repeating D in each branch.	`name: string` [required] `conditions: array<object{category:string/null, property:string/null, categoryInternal:string/null, propertyInternal:string/null, dataType:string/null, inheritFromAncestor:boolean/null, operator:string/null, comparison:string/null, value:string/null, logicalOperator:string/null, negate:boolean/null, ignoreCase:boolean/null, ignoreDiacritics:boolean/null, ignoreCharWidth:boolean/null}>` [required] `folderPath: string` [default=""] `combineOperator: string` [default="all"] `overwrite: boolean` [default=false] `selectAfterCreate: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_sets_manage`	Creates/deletes/renames/moves Selection Sets folders and static/dynamic selection/search sets. Defaults to dry-run; pass apply=true only after reviewing list_selection_sets output. Supports duplicate names via current-tree itemId or occurrence.	`operation: string` [required] `pathOrName: string` [default=""] `itemId: string` [default=""] `occurrence: integer` [default=0] `name: string` [default=""] `newName: string` [default=""] `targetFolderPath: string` [default=""] `apply: boolean` [default=false] `allowDeleteNonEmptyFolder: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_sets_reorder`	Naturally sorts Selection Sets folders and sets so names containing numbers sort numerically (1, 2, 11). Defaults to dry-run. Can sort one folder or the full tree recursively.	`folderPath: string` [default=""] `itemId: string` [default=""] `recursive: boolean` [default=true] `foldersFirst: boolean` [default=true] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`activate_saved_viewpoint`	Activates an existing saved viewpoint by exact path or unique name from list_saved_viewpoints. Defaults to dry-run and returns the resolved path without changing the view unless apply=true.	`pathOrName: string` [required] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`select_items`	Selects previously matched Navisworks items by opaque match handles.	`matchHandles: array` [required] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`hide_unselected`	Hides every item except the current Navisworks selection. Dry-run returns affected root/source-file scope summaries before applying.	`apply: boolean` [default=false] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`hide_selected`	Hides the current Navisworks selection. Dry-run returns affected root/source-file scope summaries before applying.	`apply: boolean` [default=false] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`unhide_selected`	Shows the current Navisworks selection if it is hidden. Dry-run returns affected root/source-file scope summaries before applying.	`apply: boolean` [default=false] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`reveal_selected`	Makes the current Navisworks selection actually visible by unhiding selected items and any hidden ancestors needed for visibility. Dry-run returns affected root/source-file scope summaries before applying.	`apply: boolean` [default=false] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`isolate_selected`	Shows all hidden items and then hides everything except the current Navisworks selection. Dry-run returns root/source-file scope summaries for the re-hide portion; review previouslyHiddenItemCount separately before applying.	`apply: boolean` [default=false] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`show_all`	Shows all currently hidden Navisworks items. Dry-run returns affected root/source-file scope summaries before applying.	`apply: boolean` [default=false] `previewLimit: integer` [default=10] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`create_selection_set`	Creates a static Navisworks Selection Set from the current selection or from find_items/find_root_items_by_name match handles, optionally inside a Selection Sets folder. This stores concrete model items, not a dynamic search rule. Defaults to dry-run.	`name: string` [required] `matchHandles: array` [default=null] `folderPath: string` [default=""] `overwrite: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`create_viewpoint`	Saves the current Navisworks view as a saved viewpoint, optionally inside a folder path.	`name: string` [required] `folderPath: string` [default=""] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`save_document`	Saves the active Navisworks document to its current path. This writes model changes immediately and runs on the Navisworks UI thread.	`instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`save_document_as`	Saves the active Navisworks document to a specified .nwd or .nwf path. Existing files are protected unless overwrite=true. Use .nwd to produce a self-contained deliverable with geometry.	`path: string` [required] `overwrite: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_sets_build_viewpoints`	Builds configurable saved-viewpoint steps for every non-empty Search Set or Selection Set below a required folder prefix. Each overview, markup, or sectionBox step has its own label, clustering strategy, and optional persistent markup including arrow callouts. Defaults to dry-run.	`folderPrefix: string` [required] steps: array<object{step:string/null, label:string/null, ellipseColor:array/null, thickness:integer/null, paddingFactor:number/null, markStyle:string/null, arrowCallout:boolean/null, arrowLengthMm:number/null, targetCrosshair:boolean/null, hatchAngleDeg:number/null, hatchSpacingMm:number/null, hatchSpacingPx:integer/null, hatchThickness:integer/null, fitMarginFactor:number/null, minMarkSizeMm:number/null, minRadiusPixels:integer/null, markSoloMinSizeMm:number/null, markMergeGapMm:number/null, boxOffsetMm:number/null, whenItemCountMin:integer/null, whenItemCountMax:integer/null, overwrite:boolean/null, clusterBy:string/null, clusterMaxDistanceMm:number/null, clusterTargetSize:integer/null, clusterCount:integer/null, clusterGridSizeMm:number/null, maxClusters:integer/null, maxItemsForClustering:integer/null, maxItemsForDistanceClustering:integer/null}> [required] `nameTemplate: string` [default="{set} - {step}"] `skipExisting: boolean` [default=true] `maxSetCount: integer` [default=500] `verbosity: string` [default="summary"] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`build_mtr_viewpoints`	Deprecated compatibility alias for selection_sets_build_viewpoints. Preserves the legacy MTR defaults and fixed markup/sectionBox pair. New callers should use the neutral tool.	`folderPrefix: string` [default="MTR"] `createPlan: boolean` [default=true] `createSectionBox: boolean` [default=true] `clusterMaxDistanceMm: number` [default=10000] `fitMarginFactor: number` [default=0.1] `ellipseColor: array` [default=null] `thickness: integer` [default=3] `paddingFactor: number` [default=0.2] `markStyle: string` [default="rectangle"] `arrowCallout: boolean` [default=false] `arrowLengthMm: number` [default=0] `targetCrosshair: boolean` [default=false] `hatchAngleDeg: number` [default=45] `hatchSpacingMm: number/null` [default=null] `hatchSpacingPx: integer/null` [default=null] `hatchThickness: integer` [default=3] `minMarkSizeMm: number/null` [default=null] `markSoloMinSizeMm: number` [default=1500] `markMergeGapMm: number` [default=1000] `boxOffsetMm: number` [default=1000] `skipExisting: boolean` [default=true] `maxSetCount: integer` [default=500] `maxClustersPerSet: integer` [default=10] `maxItemsForDistanceClustering: integer` [default=500] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`markup_selection`	Creates one or more saved viewpoints with persistent rectangle, target, arrow, or hatch redline marks around hybrid groups in the current selection. Large items receive individual marks; nearby small items are merged. autoTopView=true creates a top view; false preserves the current orthographic or perspective camera and its section box. Defaults to rectangle and dry-run.	`name: string` [required] `folderPath: string` [default=""] `source: string` [default="current_selection"] `autoTopView: boolean` [default=true] `fitToSelection: boolean` [default=true] `fitMarginFactor: number` [default=0.1] `ellipseColor: array` [default=null] `thickness: integer` [default=3] `paddingFactor: number` [default=0.2] `minMarkSizeMm: number/null` [default=null] `minRadiusPixels: integer/null` [default=null] `markStyle: string` [default="rectangle"] `arrowCallout: boolean` [default=false] `arrowLengthMm: number` [default=0] `targetCrosshair: boolean` [default=false] `hatchAngleDeg: number` [default=45] `hatchSpacingMm: number/null` [default=null] `hatchSpacingPx: integer/null` [default=null] `hatchThickness: integer` [default=3] `markSoloMinSizeMm: number` [default=1500] `markMergeGapMm: number` [default=1000] `clusterMaxDistanceMm: number` [default=0] `clusterBy: string` [default=""] `clusterTargetSize: integer` [default=100] `clusterCount: integer/null` [default=null] `clusterGridSizeMm: number` [default=50000] `maxClusters: integer/null` [default=null] `maxItemsForClustering: integer/null` [default=null] `maxItemsForDistanceClustering: integer/null` [default=null] `overwrite: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`live_markers`	Plans or shows runtime-only overlay markers for hybrid groups in the current selection. The markers stay attached while the camera moves but are never stored in saved viewpoints or .nwd/.nwf files. Use markup_selection for persistent deliverables.	`style: string` [default="target"] `visible: boolean` [default=true] `markerRadiusPixels: integer` [default=10] `markSoloMinSizeMm: number` [default=1500] `markMergeGapMm: number` [default=1000] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`section_box_viewpoint`	Creates one or more saved viewpoints with an enabled Navisworks section box around the current selection plus context. Optional persistent markup and line-based arrow callouts are calculated after the final ISO camera and clipping box. It never hides or isolates model items. Defaults to dry-run.	`name: string` [required] `folderPath: string` [default=""] `source: string` [default="current_selection"] `boxOffsetMm: number` [default=1000] `markStyle: string` [default=""] `arrowCallout: boolean` [default=false] `arrowLengthMm: number` [default=0] `targetCrosshair: boolean` [default=false] `ellipseColor: array` [default=null] `thickness: integer` [default=3] `paddingFactor: number` [default=0.2] `minMarkSizeMm: number/null` [default=null] `hatchAngleDeg: number` [default=45] `hatchSpacingMm: number/null` [default=null] `hatchThickness: integer` [default=3] `markSoloMinSizeMm: number` [default=1500] `markMergeGapMm: number` [default=1000] `clusterMaxDistanceMm: number` [default=0] `clusterBy: string` [default=""] `clusterTargetSize: integer` [default=100] `clusterCount: integer/null` [default=null] `clusterGridSizeMm: number` [default=50000] `maxClusters: integer/null` [default=null] `maxItemsForClustering: integer/null` [default=null] `maxItemsForDistanceClustering: integer/null` [default=null] `overwrite: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`zoom_to_selection`	Zooms the current Navisworks view to the bounding box of the current selection.	`instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`focus_on_selection`	Centers the current Navisworks view on the current selection without doing a bounding-box zoom.	`instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`fit_all`	Fits the current Navisworks view to the full model.	`instanceId: string` [default=""] `navisworksVersion: string` [default=""]


Startup and host lifecycle




Tool
Description
Parameters




list_recent_navisworks_files
Lists recent Navisworks Manage model files from the current Windows user's HKCU Recent File List registry entries. Use this before opening the last/previous Navisworks file. Does not require Navisworks to be running.
navisworksVersion: string [default=""]
limit: integer [default=10]
existingOnly: boolean [default=true]


start_navisworks
Starts Navisworks Manage. Pass filePath to open a specific .nwd/.nwf/.nwc, or set openLatestRecentFile=true to open the latest existing file from Navisworks Recent File List. Optionally waits until the NavisHelper MCP host appears and returns instanceId for follow-up tools.
navisworksVersion: string [default=""]
filePath: string [default=""]
openLatestRecentFile: boolean [default=false]
waitForHost: boolean [default=true]
waitTimeoutSeconds: integer [default=90]


open_latest_navisworks_file
Convenience tool for the user request: 'start Navisworks and open the last file'. It opens the latest existing file from Navisworks Recent File List and waits for the NavisHelper MCP host by default.
navisworksVersion: string [default=""]
waitForHost: boolean [default=true]
waitTimeoutSeconds: integer [default=90]


close_navisworks
Previews or closes one targeted Navisworks Manage instance. Modes: prompt requests normal exit and may show the native save dialog; save saves first and exits only after a verified save; discard permanently drops unsaved changes before exit. Defaults to preview and requires apply=true plus confirmClose=true. Target by instanceId, or by navisworksVersion only when exactly one matching host is running.
mode: string [default="prompt"]
savePath: string [default=""]
overwrite: boolean [default=false]
apply: boolean [default=false]
confirmClose: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


mcp_task_timer_start
Starts an optional cross-tool MCP task timer for a larger user-visible workflow that spans multiple tool calls. Call this at the beginning of a user task only when an explicit end-to-end task timer is useful, then call mcp_task_timer_finish before the final answer. Individual MCP tool calls also return automatic navishelper_timing in their primary JSON result.
taskName: string [default=""]


mcp_task_timer_finish
Finishes a cross-tool MCP task timer and returns elapsedMs, elapsedHuman, shouldReportToUser, and userMessage. If shouldReportToUser=true, include userMessage in the final answer to the user.
timerId: string [required]
taskName: string [default=""]



Selection reports and exports




Tool
Description
Parameters




selection_property_report
Returns a structured property report for the current Navisworks selection. Read-only replacement for UI/Excel property quick reports.
itemLimit: integer [default=100]
propertyLimitPerItem: integer [default=1000]
rowLimit: integer [default=10000]
includeInternalNames: boolean [default=false]
includeEmptyValues: boolean [default=false]
categoryFilters: array [default=null]
propertyFilters: array [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]


selection_export_properties
Exports the current Navisworks selection property report to an explicit CSV or XLSX file path. Defaults to dry-run; pass apply=true to write.
outputPath: string [required]
format: string [default="csv"]
apply: boolean [default=false]
overwrite: boolean [default=false]
itemLimit: integer [default=100]
propertyLimitPerItem: integer [default=1000]
rowLimit: integer [default=10000]
includeInternalNames: boolean [default=false]
includeEmptyValues: boolean [default=false]
categoryFilters: array [default=null]
propertyFilters: array [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]


selection_distinct_property_values
Returns distinct property values in the current Navisworks selection with counts. Read-only helper for reporting and future color_by_property workflows.
itemLimit: integer [default=100]
valueLimit: integer [default=1000]
includeEmptyValues: boolean [default=false]
categoryFilters: array [default=null]
propertyFilters: array [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]


selection_color_by_property
Colors the current Navisworks selection by the first matching property value. Defaults to dry-run; pass apply=true to write permanent color overrides.
apply: boolean [default=false]
itemLimit: integer [default=100]
groupLimit: integer [default=1000]
transparency: number/null [default=null]
includeEmptyValues: boolean [default=false]
categoryFilters: array [default=null]
propertyFilters: array [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Model color schemes




Tool
Description
Parameters




model_color_scheme
Analyzes model naming/property patterns or applies an explicit ordered color-classification scheme. Rules use first-match-wins priority. Mutations require apply=true; reset restores only overrides captured by the active runtime scheme.
operation: string [default="analyze"]
scope: string [default="model"]
apply: boolean [default=false]
maxItems: integer [default=100000]
candidateLimit: integer [default=100]
maxPropertiesPerItem: integer [default=50]
includeContainers: boolean [default=false]
confirmLargeApply: boolean [default=false]
clearSelectionAfterApply: boolean [default=true]
workBudgetSeconds: integer [default=40]
verbosity: string [default="compact"]
analysisCategoryFilters: array [default=null]
analysisPropertyFilters: array [default=null]
rules: array<object{name:string/null, colorHex:string/null, transparency:number/null, matchAll:boolean, nameContains:array/null, pathContains:array/null, sourceFileContains:array/null, categoryContains:array/null, propertyContains:array/null, propertyValueContains:array/null}> [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Search-and-selection workflow




Tool
Description
Parameters




select_by_search
Selects model items by Navisworks property conditions in the whole model, among one parent's direct children, or among all descendants. The search and selection happen in one call, so no runtime match handle is persisted. This changes only the current selection, not the model.
conditions: array<object{category:string/null, property:string/null, categoryInternal:string/null, propertyInternal:string/null, dataType:string/null, inheritFromAncestor:boolean/null, operator:string/null, comparison:string/null, value:string/null, logicalOperator:string/null, negate:boolean/null, ignoreCase:boolean/null, ignoreDiacritics:boolean/null, ignoreCharWidth:boolean/null}> [required]
scope: string [default="whole_model"]
parentConditions: array<object{category:string/null, property:string/null, categoryInternal:string/null, propertyInternal:string/null, dataType:string/null, inheritFromAncestor:boolean/null, operator:string/null, comparison:string/null, value:string/null, logicalOperator:string/null, negate:boolean/null, ignoreCase:boolean/null, ignoreDiacritics:boolean/null, ignoreCharWidth:boolean/null}> [default=null]
replaceSelection: boolean [default=true]
maxMatchedItems: integer [default=5000]
previewLimit: integer [default=10]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Clash tests, results, reports, and viewpoints




Tool
Description
Parameters




clash_list_tests
Lists Clash Detective tests in the active Navisworks document and returns per-test clash counts. Read-only.
limit: integer [default=200]
offset: integer [default=0]
namePrefix: string [default=""]
nameContains: string [default=""]
includeStatusCounts: boolean [default=true]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_list_results
Lists Clash Detective results from all tests or a named test. Read-only. Use after clash_list_tests to inspect statuses, assignees, and clashing item names.
testName: string [default=""]
limit: integer [default=500]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=false]
resultOffset: integer [default=0]
includeItemNames: boolean [default=true]
includeAssignedTo: boolean [default=true]
includeIgnored: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_list_clusters
Groups existing Clash Detective results into read-only clusters. Default groupMode=hybrid first groups by associated object pair, then splits by clash-point proximity; this does not require reliable discipline/architecture classification. Use to collapse many raw clashes into practical problem zones such as pump building vs pump pipelines. Does not mutate the document.
testName: string [default=""]
testNames: array [default=null]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=false]
groupMode: string [default="hybrid"]
clusterDistanceMm: number [default=300]
limit: integer [default=100]
resultOffset: integer [default=0]
previewRowsPerCluster: integer [default=5]
maxResults: integer [default=500]
excludeItemNameContains: array [default=null]
verbosity: string [default="compact"]
includeIgnored: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_group_results
Creates real Clash Detective result groups from existing clash results by formula. The groups array is paged and reports plannedGroupCount, returnedGroupCount, groupsTruncated, and nextGroupOffset. Defaults to dry-run.
apply: boolean [default=false]
testName: string [default=""]
testNames: array [default=null]
testHandles: array [default=null]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=false]
groupBySide: string [default="B"]
groupBy: string [default="ancestor"]
ancestorLevelsUp: integer [default=1]
groupNameMode: string [default="owner_name"]
groupNamePrefix: string [default=""]
includeNavisHelperSideTag: boolean [default=true]
overwriteExisting: boolean [default=false]
ungroupExistingFirst: boolean [default=false]
minGroupSize: integer [default=2]
maxResults: integer [default=500]
previewRowsPerGroup: integer [default=5]
groupOffset: integer [default=0]
groupLimit: integer [default=500]
aggregateOnly: boolean [default=false]
confirmLargeGrouping: boolean [default=false]
excludeItemNameContains: array [default=null]
verbosity: string [default="compact"]
includeIgnored: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_group_custom
Creates or rebuilds one real ClashResultGroup from explicit result handles. All handles are validated before mutation. Dry-run by default.
testHandle: string [required]
resultHandles: array [required]
groupName: string [required]
apply: boolean [default=false]
overwriteExisting: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_ungroup
Ungroups explicit ClashResultGroup handles or groups matching a name prefix within one test. Dry-run by default.
testHandle: string [required]
groupHandles: array [default=null]
groupNamePrefix: string [default=""]
apply: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_set_status
Sets status on explicit results, all results in groups, or whole tests. Group/test scopes cascade to individual results. Dry-run by default.
scope: string [required]
status: string [required]
testHandle: string [default=""]
resultHandles: array [default=null]
groupHandles: array [default=null]
testHandles: array [default=null]
assignedTo: string [default=""]
comment: string [default=""]
apply: boolean [default=false]
confirmLargeStatusChange: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_group_by_proximity
Clusters clash points and writes real ClashResultGroup folders per test. Supports spatial, hybrid, and object_pair modes. Dry-run by default.
testName: string [default=""]
testNames: array [default=null]
testHandles: array [default=null]
groupMode: string [default="hybrid"]
clusterDistanceMm: number [default=500]
minGroupSize: integer [default=2]
groupNameTemplate: string [default="Зона {index:D2} ({count} колл.)"]
groupNamePrefix: string [default=""]
ungroupExistingFirst: boolean [default=false]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=false]
excludeItemNameContains: array [default=null]
maxResults: integer [default=500]
includeIgnored: boolean [default=false]
apply: boolean [default=false]
confirmLargeGrouping: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_ignore_rules
Lists, adds, or removes document-persistent clash ignore rules. Added rules approve matching results with a reason comment and are re-applied after test runs. Dry-run for add/remove by default.
action: string [required]
rule: object{name:string/null, testNamePattern:string/null, itemAContains:array/null, itemBContains:array/null, reason:string/null} [default=null]
ruleName: string [default=""]
apply: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_export_points
Exports clash points to CSV or XLSX with global/local coordinates, level assignment, grid cells, and XLSX summary sheets. Dry-run by default.
outputPath: string [required]
testNames: array [default=null]
testHandles: array [default=null]
origin: object{x:number, y:number, z:number} [default=null]
rotationDeg: number [default=0]
levels: array<object{name:string/null, zFrom:number, zTo:number}> [default=null]
gridSizeM: number [default=6]
includeIgnored: boolean [default=false]
apply: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_renumber_results
Renumbers Clash Detective groups and/or individual clash results inside selected tests. Defaults to dry-run and top-level scope, so existing groups and ungrouped results are numbered as the user sees them in the standard form. Pass apply=true and confirmRename=true only after reviewing the plan.
apply: boolean [default=false]
testName: string [default=""]
testNames: array [default=null]
testHandles: array [default=null]
scope: string [default="top_level"]
orderBy: string [default="current"]
startNumber: integer [default=1]
numberWidth: integer [default=4]
separator: string [default=" - "]
prefix: string [default=""]
suffix: string [default=""]
preserveExistingName: boolean [default=true]
stripExistingNumber: boolean [default=true]
includeGroups: boolean [default=true]
includeResults: boolean [default=true]
includeEmptyGroups: boolean [default=false]
confirmRename: boolean [default=false]
limit: integer [default=5000]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_bbox_pair_plan
Plans candidate Clash Detective group pairs by intersecting bounding boxes from top-level roots or the current arbitrary selection. Does not mutate the Navisworks document. Defaults to preview; apply=true writes outputPath. Never creates or runs tests. Use sourceMode=selection for nested discipline groups and refineDepth=1 or 2 to reduce broad-box false positives.
apply: boolean [default=false]
rootMode: string [default="top_level_files"]
sourceMode: string [default="top_level_files"]
rootNames: array [default=null]
nameContains: string [default=""]
excludeNameContains: array [default=null]
targetRootName: string [default=""]
refineDepth: integer [default=1]
bboxToleranceMm: number [default=0]
maxRootItems: integer [default=500]
maxCandidatePairs: integer [default=50000]
previewLimit: integer [default=200]
includeRejected: boolean [default=false]
outputPath: string [default=""]
overwriteExisting: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_pair_tests_create
Creates Clash Detective tests from bbox candidate pairs. Defaults to dry-run; pass apply=true only after reviewing planned test names/selections. This does not run created tests.
apply: boolean [default=false]
pairs: array<object{index:integer, a:object/null, b:object/null, checkedChildPairCount:integer, childIntersectingPairCount:integer, reason:string/null}> [default=null]
planOutputPath: string [default=""]
testNamePrefix: string [default="NH-BBOX"]
limit: integer [default=200]
toleranceMm: number [default=-1]
testType: string [default=""]
settingsFromTestName: string [default=""]
overwriteExisting: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_create_matrix_from_selection
Creates Clash Detective matrix tests from the current Navisworks selection or explicit matrix items: every item against every other item (i<j), with no self-clash. Defaults to dry-run and no generated name prefix unless useGeneratedPrefix=true.
apply: boolean [default=false]
namePrefix: string [default=""]
useGeneratedPrefix: boolean [default=false]
toleranceMm: number [default=-1]
testType: string [default="hard"]
runAfterCreate: boolean [default=false]
removePreviousGenerated: boolean [default=false]
matrixItemNames: array [default=null]
matrixNameContains: string [default=""]
matrixExcludeNameContains: array [default=null]
maxSelectedItems: integer [default=100]
confirmLargeMatrix: boolean [default=false]
includePairNames: boolean [default=true]
pairNameTemplate: string [default=""]
pairNameStartIndex: integer [default=1]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_generate_report
Generates a NavisHelper Clash Report workflow from existing Clash Detective results. Defaults to dry-run; pass apply=true to create section-box viewpoints, screenshots when available, and HTML/JSON artifacts.
apply: boolean [default=false]
testName: string [default=""]
testNames: array [default=null]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=false]
limit: integer [default=100]
resultOffset: integer [default=0]
outputDirectory: string [default=""]
overwrite: boolean [default=false]
append: boolean [default=false]
confirmLargeReport: boolean [default=false]
runTests: boolean [default=false]
boxOffsetMm: number [default=1500]
boxMode: string [default="point"]
contextTransparency: number [default=0.5]
useFullBoxTransparency: boolean [default=false]
groupMode: string [default="none"]
artifactGranularity: string [default="result"]
verbosity: string [default="full"]
clusterDistanceMm: number [default=300]
includeClusterMembers: boolean [default=true]
maxMembersPerClusterInHtml: integer [default=25]
colorAHex: string [default=""]
colorBHex: string [default=""]
createViewpoints: boolean [default=true]
captureScreenshots: boolean [default=true]
includeClashPointMarker: boolean [default=false]
captureTopViewScreenshots: boolean [default=false]
screenshotProfile: string [default="compact"]
screenshotFormat: string [default=""]
screenshotMaxWidth: integer [default=0]
screenshotMaxHeight: integer [default=0]
screenshotJpegQuality: integer [default=0]
excludeItemNameContains: array [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_save_viewpoints
Creates Saved Viewpoints from existing Clash Detective results only. Defaults to dry-run; pass apply=true to save viewpoints. This does not run tests, generate reports, write files, or capture screenshots.
apply: boolean [default=false]
testName: string [default=""]
testNames: array [default=null]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=false]
limit: integer [default=100]
resultOffset: integer [default=0]
confirmLargeViewpoints: boolean [default=false]
folderPath: string [default=""]
createResetViewpoint: boolean [default=true]
boxOffsetMm: number [default=1500]
boxMode: string [default="point"]
contextTransparency: number [default=0.5]
useFullBoxTransparency: boolean [default=false]
useRootContextTransparency: boolean [default=false]
createOppositeViewpoints: boolean [default=false]
colorAHex: string [default=""]
colorBHex: string [default=""]
includeClashPointMarker: boolean [default=false]
excludeItemNameContains: array [default=null]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_report_status
Returns status for the active or last clash_generate_report operation. This can be called while a large report is running.
operationId: string [default=""]
instanceId: string [default=""]
navisworksVersion: string [default=""]


cancel_clash_report
Requests cooperative cancellation of the active clash_generate_report operation. The current screenshot/viewpoint step may finish, then the report writes partial artifacts and stops before the next clash.
operationId: string [default=""]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_manage_tests
Runs, deletes, renames, reorders, sorts, or edits selected Clash Detective tests by name, handle, prefix, or first-N scope. Defaults to dry-run; pass apply=true for run/reset/compact/rename/delete/move/sort/set_settings. operation=run only executes tests; it does not save the model, create reports, screenshots, or viewpoints. Use clash_list_tests first to get testHandles.
operation: string [required]
apply: boolean [default=false]
testName: string [default=""]
testNames: array [default=null]
testHandles: array [default=null]
namePrefix: string [default=""]
firstN: integer [default=0]
newName: string [default=""]
renames: array<object{testHandle:string/null, newName:string/null}> [default=null]
namePattern: string [default=""]
renameStartIndex: integer [default=1]
renameFromEnd: boolean [default=false]
targetIndex: integer [default=0]
sortDirection: string [default="asc"]
toleranceMm: number [default=-1]
testType: string [default=""]
onlyWithTotal: integer [default=-1]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Clash isolation and screenshots




Tool
Description
Parameters




clash_isolate_result
Previews and optionally isolates one existing Clash Detective result by resultHandle. Can highlight A/B, clip around the clash point or item bounds, hide everything except the pair, choose a preset or custom camera, and optionally capture a screenshot. Defaults to dry-run.
resultHandle: string [required]
boxMode: string [default="point"]
boxOffsetMm: number [default=1000]
useSectionBox: boolean [default=true]
isolatePair: boolean [default=false]
useContextTransparency: boolean [default=false]
contextTransparency: number [default=0.7]
colorAHex: string [default=""]
colorBHex: string [default=""]
cameraMode: string [default="current"]
cameraPosition: object{x:number, y:number, z:number} [default=null]
cameraTarget: object{x:number, y:number, z:number} [default=null]
cameraUp: object{x:number, y:number, z:number} [default=null]
projection: string [default="current"]
screenshotPath: string [default=""]
screenshotProfile: string [default="compact"]
screenshotFormat: string [default=""]
screenshotMaxWidth: integer/null [default=null]
screenshotMaxHeight: integer/null [default=null]
screenshotJpegQuality: integer/null [default=null]
overwriteScreenshot: boolean [default=false]
apply: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_reset_isolation
Restores the viewpoint, section box, appearance overrides, and temporary visibility changed by clash_isolate_result in the active document. Defaults to dry-run.
apply: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


capture_current_view
Captures the current Navisworks view exactly as displayed. Use after clash_isolate_result or after manually choosing any camera angle. Defaults to dry-run.
outputPath: string [required]
screenshotProfile: string [default="compact"]
screenshotFormat: string [default=""]
screenshotMaxWidth: integer/null [default=null]
screenshotMaxHeight: integer/null [default=null]
screenshotJpegQuality: integer/null [default=null]
overwrite: boolean [default=false]
apply: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Clash root matrix




Tool
Description
Parameters




clash_root_matrix
Builds a paged {(rootA, rootB): clashCount} coordination matrix from existing Clash Detective results. Root identity comes directly from each ModelItem.Model, so it does not depend on tree depth or parsing .rvm names from owner paths.
testName: string [default=""]
testNames: array [default=null]
testHandles: array [default=null]
statusFilters: array [default=null]
includeAllStatuses: boolean [default=true]
ignoreSameFile: boolean [default=true]
offset: integer [default=0]
limit: integer [default=500]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Clash workflows from saved sets




Tool
Description
Parameters




clash_tests_from_sets
Creates one Clash Detective test per Selection Set/Search Set pair. Both test sides use native live Navisworks SelectionSource bindings, so dynamic Search Sets are re-evaluated on later runs. Dry-run by default. References accept itemId (preferred), full path, or unique name. pairNameTemplate supports {index}, {aName}, {bName}, {aCode}, {bCode} and zeroPad/strip/replace/upper/lower transforms.
apply: boolean [default=false]
pairs: array<object{a:object/null, b:object/null, name:string/null}> [default=null]
planPath: string [default=""]
testType: string [default="hard"]
toleranceMm: number [default=-1]
pairNameTemplate: string [default="{index


clash_run_batch
Starts an asynchronous Clash Detective run and returns immediately with operationId. Runs one Navisworks test per UI callback, pauses after batchSize, and keeps clash_run_status/cancel_clash_run available even while a test is calculating. Dry-run by default.
apply: boolean [default=false]
testNames: array [default=null]
testHandles: array [default=null]
namePrefix: string [default=""]
firstN: integer [default=0]
batchSize: integer [default=10]
perTestTimeoutSeconds: integer [default=300]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_run_resume
Continues a paused asynchronous clash run for the next batch.
operationId: string [required]
batchSize: integer [default=0]
instanceId: string [default=""]
navisworksVersion: string [default=""]


clash_run_status
Returns progress and per-test outcomes for an asynchronous clash run. Read-only and bypasses host_busy.
operationId: string [required]
waitSeconds: integer [default=0]
waitForCompletion: boolean [default=false]
instanceId: string [default=""]
navisworksVersion: string [default=""]


cancel_clash_run
Requests cooperative cancellation of an asynchronous clash run. It bypasses host_busy. A currently executing native Navisworks test finishes first; no later test is started.
operationId: string [required]
instanceId: string [default=""]
navisworksVersion: string [default=""]



Reusable MCP scenarios




Tool
Description
Parameters




scenario_capabilities
Returns supported scenario schema versions, complete tool allowlist, contract versions, reviewed writes, safe output projections, parameter/$stepResult syntax, foreach rules, pair-name grammar, and a complete valid example. Read-only.
None.


list_scenarios
Lists user-approved NavisHelper scenarios from the current Windows profile. Returns metadata and bounded context-match suggestions only; it never executes scenario steps.
query: string [default=""]
navisworksVersion: string [default=""]
rootFileNames: array [default=null]
projectLabel: string [default=""]
limit: integer [default=3]


get_scenario
Reads one saved NavisHelper scenario by scenario_id. This is read-only and does not resolve parameters or execute any step.
scenarioId: string [required]


save_scenario
Validates and saves a user-approved NavisHelper schema v1/v2 scenario under %APPDATA%\NavisHelper\Scenarios. Defaults to preview. Use {"$parameter":"name"}; schema v2 also supports allowlisted {"$stepResult":"step.output"}, bounded foreach, typed parameters, and per-tool reviewedWrites. stepId must match ^[A-Za-z][A-Za-z0-9_]{0,63}$. Call scenario_capabilities for the full grammar and example. Never store apply/confirm flags, handles, instance/document IDs, credentials, or raw transcripts.
scenario: object{schemaVersion:integer, executionMode:string/null, name:string/null, description:string/null, context:object{navisworksVersions:array/null, rootFilePatterns:array/null, projectLabel:string/null}/null, parameters:array/null, steps:array/null, exactReplay:object{fixedParameters:object/null, contextPolicy:string/null, writePolicy:string/null, safetyEnvelope:object/null}/null} [required]
scenarioId: string [default=""]
expectedSha256: string [default=""]
apply: boolean [default=false]
confirmSave: boolean [default=false]
confirmExactReplay: boolean [default=false]


delete_scenario
Deletes exactly one saved NavisHelper scenario. Defaults to preview and uses SHA-256 optimistic concurrency. It never recursively deletes the scenario directory.
scenarioId: string [required]
expectedSha256: string [default=""]
apply: boolean [default=false]
confirmDelete: boolean [default=false]


resolve_scenario
Resolves a saved scenario into ordered existing MCP tool calls without executing them. For template mode, show the plan and obtain normal apply confirmation. For exactReplay, a direct user replay request is current authorization: follow agent_instruction, run each preview, enforce the saved safety envelope, then apply without follow-up questions; stop on the first mismatch.
scenarioId: string [required]
parameterValues: object [default=null]
executionIntent: string [default="preview"]
navisworksVersion: string [default=""]
rootFileNames: array [default=null]
projectLabel: string [default=""]



Status and limitations


Navisworks Manage is supported; the bundle does not declare Navisworks Simulate.
Most tools require a running Navisworks plugin host. Model operations additionally require an active document, and view operations require an active view.
Autodesk API work runs on the Navisworks UI thread. Concurrent calls to one host can return host_busy; manual interactive NavisHelper work can return interactive_busy.
The default bridge timeout is 60 seconds plus a 5-second transport margin. A single named-pipe frame is limited to 4 MiB; large workflows use paging, compact responses, file exports, or chunked jobs.
With multiple Navisworks windows, use instanceId or a Navisworks version that selects exactly one host. Match handles and tree item IDs are scoped to the current host, document, and tree session.
find_items_by_bbox uses axis-aligned bounding boxes in global document coordinates and active-model units. It does not transform local or grid coordinates.
Persisted Navisworks Search Sets support a narrower condition set than transient find_items. Native conditions have no parentheses, and AND has higher precedence than OR.
saved_viewpoints_import restores cameras, folders, and simple line/ellipse redlines. Other redline types, clip planes, hide overrides, and material overrides are returned as warnings rather than restored.
Clash tools require the Navisworks Manage Clash Detective API and existing tests or results in the active document. Native clash execution is synchronous; cancellation is cooperative.
Screenshot generation is best-effort and depends on the Navisworks image export plugin.
The plugin build references Autodesk SDK assemblies at standard C:\Program Files\Autodesk\Navisworks Manage 20XX\ paths. Plain Debug and Release target Navisworks 2026; a four-version release requires Release2024 through Release2027.
Direct DevExpress 25.1 references remain in the 2026/2027 project configuration although related UI imports are commented out. Whether these references are required for a public build is unresolved. 
GitHub-hosted CI cannot build the complete Navisworks matrix because Autodesk SDK assemblies are unavailable on hosted runners; the full matrix and installer are built locally.
No public, sanitized Navisworks test model is tracked in the repository. Live smoke testing requires a user-provided test model. 
AIColorObjects retains a legacy file-IPC path that looks for ColorService.exe, but that executable is not included in the solution, installer, or distribution package; the current shipped AI configuration is OpenRouter/BYOK. 
The plugin UI (ribbon, dialogs, log messages) is currently Russian-only. English localization is planned as a separate follow-up, not yet implemented.

This project is maintained at low activity. PRs are welcome; responses to issues are not guaranteed.
License

MIT.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
ColorService		ColorService
NavisHelper.Contracts		NavisHelper.Contracts
NavisHelper.Dev		NavisHelper.Dev
NavisHelper.McpConfigurator		NavisHelper.McpConfigurator
NavisHelper.McpServer.Tests		NavisHelper.McpServer.Tests
NavisHelper.McpServer		NavisHelper.McpServer
NavisHelper.bundle		NavisHelper.bundle
NavisHelper		NavisHelper
docs		docs
installer		installer
licenses		licenses
scripts		scripts
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
BUILD_BUNDLE_RULES.md		BUILD_BUNDLE_RULES.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NavisHelper.sln		NavisHelper.sln
README.md		README.md
README.ru.md		README.ru.md
THIRD-PARTY-NOTICES.md		THIRD-PARTY-NOTICES.md

Tool	Description	Parameters
`list_recent_navisworks_files`	Lists recent Navisworks Manage model files from the current Windows user's HKCU Recent File List registry entries. Use this before opening the last/previous Navisworks file. Does not require Navisworks to be running.	`navisworksVersion: string` [default=""] `limit: integer` [default=10] `existingOnly: boolean` [default=true]
`start_navisworks`	Starts Navisworks Manage. Pass filePath to open a specific .nwd/.nwf/.nwc, or set openLatestRecentFile=true to open the latest existing file from Navisworks Recent File List. Optionally waits until the NavisHelper MCP host appears and returns instanceId for follow-up tools.	`navisworksVersion: string` [default=""] `filePath: string` [default=""] `openLatestRecentFile: boolean` [default=false] `waitForHost: boolean` [default=true] `waitTimeoutSeconds: integer` [default=90]
`open_latest_navisworks_file`	Convenience tool for the user request: 'start Navisworks and open the last file'. It opens the latest existing file from Navisworks Recent File List and waits for the NavisHelper MCP host by default.	`navisworksVersion: string` [default=""] `waitForHost: boolean` [default=true] `waitTimeoutSeconds: integer` [default=90]
`close_navisworks`	Previews or closes one targeted Navisworks Manage instance. Modes: prompt requests normal exit and may show the native save dialog; save saves first and exits only after a verified save; discard permanently drops unsaved changes before exit. Defaults to preview and requires apply=true plus confirmClose=true. Target by instanceId, or by navisworksVersion only when exactly one matching host is running.	`mode: string` [default="prompt"] `savePath: string` [default=""] `overwrite: boolean` [default=false] `apply: boolean` [default=false] `confirmClose: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`mcp_task_timer_start`	Starts an optional cross-tool MCP task timer for a larger user-visible workflow that spans multiple tool calls. Call this at the beginning of a user task only when an explicit end-to-end task timer is useful, then call mcp_task_timer_finish before the final answer. Individual MCP tool calls also return automatic navishelper_timing in their primary JSON result.	`taskName: string` [default=""]
`mcp_task_timer_finish`	Finishes a cross-tool MCP task timer and returns elapsedMs, elapsedHuman, shouldReportToUser, and userMessage. If shouldReportToUser=true, include userMessage in the final answer to the user.	`timerId: string` [required] `taskName: string` [default=""]

Tool	Description	Parameters
`clash_list_tests`	Lists Clash Detective tests in the active Navisworks document and returns per-test clash counts. Read-only.	`limit: integer` [default=200] `offset: integer` [default=0] `namePrefix: string` [default=""] `nameContains: string` [default=""] `includeStatusCounts: boolean` [default=true] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_list_results`	Lists Clash Detective results from all tests or a named test. Read-only. Use after clash_list_tests to inspect statuses, assignees, and clashing item names.	`testName: string` [default=""] `limit: integer` [default=500] `statusFilters: array` [default=null] `includeAllStatuses: boolean` [default=false] `resultOffset: integer` [default=0] `includeItemNames: boolean` [default=true] `includeAssignedTo: boolean` [default=true] `includeIgnored: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_list_clusters`	Groups existing Clash Detective results into read-only clusters. Default groupMode=hybrid first groups by associated object pair, then splits by clash-point proximity; this does not require reliable discipline/architecture classification. Use to collapse many raw clashes into practical problem zones such as pump building vs pump pipelines. Does not mutate the document.	`testName: string` [default=""] `testNames: array` [default=null] `statusFilters: array` [default=null] `includeAllStatuses: boolean` [default=false] `groupMode: string` [default="hybrid"] `clusterDistanceMm: number` [default=300] `limit: integer` [default=100] `resultOffset: integer` [default=0] `previewRowsPerCluster: integer` [default=5] `maxResults: integer` [default=500] `excludeItemNameContains: array` [default=null] `verbosity: string` [default="compact"] `includeIgnored: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_group_results`	Creates real Clash Detective result groups from existing clash results by formula. The groups array is paged and reports plannedGroupCount, returnedGroupCount, groupsTruncated, and nextGroupOffset. Defaults to dry-run.	`apply: boolean` [default=false] `testName: string` [default=""] `testNames: array` [default=null] `testHandles: array` [default=null] `statusFilters: array` [default=null] `includeAllStatuses: boolean` [default=false] `groupBySide: string` [default="B"] `groupBy: string` [default="ancestor"] `ancestorLevelsUp: integer` [default=1] `groupNameMode: string` [default="owner_name"] `groupNamePrefix: string` [default=""] `includeNavisHelperSideTag: boolean` [default=true] `overwriteExisting: boolean` [default=false] `ungroupExistingFirst: boolean` [default=false] `minGroupSize: integer` [default=2] `maxResults: integer` [default=500] `previewRowsPerGroup: integer` [default=5] `groupOffset: integer` [default=0] `groupLimit: integer` [default=500] `aggregateOnly: boolean` [default=false] `confirmLargeGrouping: boolean` [default=false] `excludeItemNameContains: array` [default=null] `verbosity: string` [default="compact"] `includeIgnored: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_group_custom`	Creates or rebuilds one real ClashResultGroup from explicit result handles. All handles are validated before mutation. Dry-run by default.	`testHandle: string` [required] `resultHandles: array` [required] `groupName: string` [required] `apply: boolean` [default=false] `overwriteExisting: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_ungroup`	Ungroups explicit ClashResultGroup handles or groups matching a name prefix within one test. Dry-run by default.	`testHandle: string` [required] `groupHandles: array` [default=null] `groupNamePrefix: string` [default=""] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_set_status`	Sets status on explicit results, all results in groups, or whole tests. Group/test scopes cascade to individual results. Dry-run by default.	`scope: string` [required] `status: string` [required] `testHandle: string` [default=""] `resultHandles: array` [default=null] `groupHandles: array` [default=null] `testHandles: array` [default=null] `assignedTo: string` [default=""] `comment: string` [default=""] `apply: boolean` [default=false] `confirmLargeStatusChange: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_group_by_proximity`	Clusters clash points and writes real ClashResultGroup folders per test. Supports spatial, hybrid, and object_pair modes. Dry-run by default.	`testName: string` [default=""] `testNames: array` [default=null] `testHandles: array` [default=null] `groupMode: string` [default="hybrid"] `clusterDistanceMm: number` [default=500] `minGroupSize: integer` [default=2] `groupNameTemplate: string` [default="Зона {index:D2} ({count} колл.)"] `groupNamePrefix: string` [default=""] `ungroupExistingFirst: boolean` [default=false] `statusFilters: array` [default=null] `includeAllStatuses: boolean` [default=false] `excludeItemNameContains: array` [default=null] `maxResults: integer` [default=500] `includeIgnored: boolean` [default=false] `apply: boolean` [default=false] `confirmLargeGrouping: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_ignore_rules`	Lists, adds, or removes document-persistent clash ignore rules. Added rules approve matching results with a reason comment and are re-applied after test runs. Dry-run for add/remove by default.	`action: string` [required] `rule: object{name:string/null, testNamePattern:string/null, itemAContains:array/null, itemBContains:array/null, reason:string/null}` [default=null] `ruleName: string` [default=""] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_export_points`	Exports clash points to CSV or XLSX with global/local coordinates, level assignment, grid cells, and XLSX summary sheets. Dry-run by default.	`outputPath: string` [required] `testNames: array` [default=null] `testHandles: array` [default=null] `origin: object{x:number, y:number, z:number}` [default=null] `rotationDeg: number` [default=0] `levels: array<object{name:string/null, zFrom:number, zTo:number}>` [default=null] `gridSizeM: number` [default=6] `includeIgnored: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_renumber_results`	Renumbers Clash Detective groups and/or individual clash results inside selected tests. Defaults to dry-run and top-level scope, so existing groups and ungrouped results are numbered as the user sees them in the standard form. Pass apply=true and confirmRename=true only after reviewing the plan.	`apply: boolean` [default=false] `testName: string` [default=""] `testNames: array` [default=null] `testHandles: array` [default=null] `scope: string` [default="top_level"] `orderBy: string` [default="current"] `startNumber: integer` [default=1] `numberWidth: integer` [default=4] `separator: string` [default=" - "] `prefix: string` [default=""] `suffix: string` [default=""] `preserveExistingName: boolean` [default=true] `stripExistingNumber: boolean` [default=true] `includeGroups: boolean` [default=true] `includeResults: boolean` [default=true] `includeEmptyGroups: boolean` [default=false] `confirmRename: boolean` [default=false] `limit: integer` [default=5000] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_bbox_pair_plan`	Plans candidate Clash Detective group pairs by intersecting bounding boxes from top-level roots or the current arbitrary selection. Does not mutate the Navisworks document. Defaults to preview; apply=true writes outputPath. Never creates or runs tests. Use sourceMode=selection for nested discipline groups and refineDepth=1 or 2 to reduce broad-box false positives.	`apply: boolean` [default=false] `rootMode: string` [default="top_level_files"] `sourceMode: string` [default="top_level_files"] `rootNames: array` [default=null] `nameContains: string` [default=""] `excludeNameContains: array` [default=null] `targetRootName: string` [default=""] `refineDepth: integer` [default=1] `bboxToleranceMm: number` [default=0] `maxRootItems: integer` [default=500] `maxCandidatePairs: integer` [default=50000] `previewLimit: integer` [default=200] `includeRejected: boolean` [default=false] `outputPath: string` [default=""] `overwriteExisting: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_pair_tests_create`	Creates Clash Detective tests from bbox candidate pairs. Defaults to dry-run; pass apply=true only after reviewing planned test names/selections. This does not run created tests.	`apply: boolean` [default=false] `pairs: array<object{index:integer, a:object/null, b:object/null, checkedChildPairCount:integer, childIntersectingPairCount:integer, reason:string/null}>` [default=null] `planOutputPath: string` [default=""] `testNamePrefix: string` [default="NH-BBOX"] `limit: integer` [default=200] `toleranceMm: number` [default=-1] `testType: string` [default=""] `settingsFromTestName: string` [default=""] `overwriteExisting: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_create_matrix_from_selection`	Creates Clash Detective matrix tests from the current Navisworks selection or explicit matrix items: every item against every other item (i<j), with no self-clash. Defaults to dry-run and no generated name prefix unless useGeneratedPrefix=true.	`apply: boolean` [default=false] `namePrefix: string` [default=""] `useGeneratedPrefix: boolean` [default=false] `toleranceMm: number` [default=-1] `testType: string` [default="hard"] `runAfterCreate: boolean` [default=false] `removePreviousGenerated: boolean` [default=false] `matrixItemNames: array` [default=null] `matrixNameContains: string` [default=""] `matrixExcludeNameContains: array` [default=null] `maxSelectedItems: integer` [default=100] `confirmLargeMatrix: boolean` [default=false] `includePairNames: boolean` [default=true] `pairNameTemplate: string` [default=""] `pairNameStartIndex: integer` [default=1] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_generate_report`	Generates a NavisHelper Clash Report workflow from existing Clash Detective results. Defaults to dry-run; pass apply=true to create section-box viewpoints, screenshots when available, and HTML/JSON artifacts.	`apply: boolean` [default=false] `testName: string` [default=""] `testNames: array` [default=null] `statusFilters: array` [default=null] `includeAllStatuses: boolean` [default=false] `limit: integer` [default=100] `resultOffset: integer` [default=0] `outputDirectory: string` [default=""] `overwrite: boolean` [default=false] `append: boolean` [default=false] `confirmLargeReport: boolean` [default=false] `runTests: boolean` [default=false] `boxOffsetMm: number` [default=1500] `boxMode: string` [default="point"] `contextTransparency: number` [default=0.5] `useFullBoxTransparency: boolean` [default=false] `groupMode: string` [default="none"] `artifactGranularity: string` [default="result"] `verbosity: string` [default="full"] `clusterDistanceMm: number` [default=300] `includeClusterMembers: boolean` [default=true] `maxMembersPerClusterInHtml: integer` [default=25] `colorAHex: string` [default=""] `colorBHex: string` [default=""] `createViewpoints: boolean` [default=true] `captureScreenshots: boolean` [default=true] `includeClashPointMarker: boolean` [default=false] `captureTopViewScreenshots: boolean` [default=false] `screenshotProfile: string` [default="compact"] `screenshotFormat: string` [default=""] `screenshotMaxWidth: integer` [default=0] `screenshotMaxHeight: integer` [default=0] `screenshotJpegQuality: integer` [default=0] `excludeItemNameContains: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_save_viewpoints`	Creates Saved Viewpoints from existing Clash Detective results only. Defaults to dry-run; pass apply=true to save viewpoints. This does not run tests, generate reports, write files, or capture screenshots.	`apply: boolean` [default=false] `testName: string` [default=""] `testNames: array` [default=null] `statusFilters: array` [default=null] `includeAllStatuses: boolean` [default=false] `limit: integer` [default=100] `resultOffset: integer` [default=0] `confirmLargeViewpoints: boolean` [default=false] `folderPath: string` [default=""] `createResetViewpoint: boolean` [default=true] `boxOffsetMm: number` [default=1500] `boxMode: string` [default="point"] `contextTransparency: number` [default=0.5] `useFullBoxTransparency: boolean` [default=false] `useRootContextTransparency: boolean` [default=false] `createOppositeViewpoints: boolean` [default=false] `colorAHex: string` [default=""] `colorBHex: string` [default=""] `includeClashPointMarker: boolean` [default=false] `excludeItemNameContains: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_report_status`	Returns status for the active or last clash_generate_report operation. This can be called while a large report is running.	`operationId: string` [default=""] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`cancel_clash_report`	Requests cooperative cancellation of the active clash_generate_report operation. The current screenshot/viewpoint step may finish, then the report writes partial artifacts and stops before the next clash.	`operationId: string` [default=""] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_manage_tests`	Runs, deletes, renames, reorders, sorts, or edits selected Clash Detective tests by name, handle, prefix, or first-N scope. Defaults to dry-run; pass apply=true for run/reset/compact/rename/delete/move/sort/set_settings. operation=run only executes tests; it does not save the model, create reports, screenshots, or viewpoints. Use clash_list_tests first to get testHandles.	`operation: string` [required] `apply: boolean` [default=false] `testName: string` [default=""] `testNames: array` [default=null] `testHandles: array` [default=null] `namePrefix: string` [default=""] `firstN: integer` [default=0] `newName: string` [default=""] `renames: array<object{testHandle:string/null, newName:string/null}>` [default=null] `namePattern: string` [default=""] `renameStartIndex: integer` [default=1] `renameFromEnd: boolean` [default=false] `targetIndex: integer` [default=0] `sortDirection: string` [default="asc"] `toleranceMm: number` [default=-1] `testType: string` [default=""] `onlyWithTotal: integer` [default=-1] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]

Tool	Description	Parameters
`clash_tests_from_sets`	Creates one Clash Detective test per Selection Set/Search Set pair. Both test sides use native live Navisworks SelectionSource bindings, so dynamic Search Sets are re-evaluated on later runs. Dry-run by default. References accept itemId (preferred), full path, or unique name. pairNameTemplate supports {index}, {aName}, {bName}, {aCode}, {bCode} and zeroPad/strip/replace/upper/lower transforms.	`apply: boolean` [default=false] `pairs: array<object{a:object/null, b:object/null, name:string/null}>` [default=null] `planPath: string` [default=""] `testType: string` [default="hard"] `toleranceMm: number` [default=-1] `pairNameTemplate: string` [default="{index
`clash_run_batch`	Starts an asynchronous Clash Detective run and returns immediately with operationId. Runs one Navisworks test per UI callback, pauses after batchSize, and keeps clash_run_status/cancel_clash_run available even while a test is calculating. Dry-run by default.	`apply: boolean` [default=false] `testNames: array` [default=null] `testHandles: array` [default=null] `namePrefix: string` [default=""] `firstN: integer` [default=0] `batchSize: integer` [default=10] `perTestTimeoutSeconds: integer` [default=300] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_run_resume`	Continues a paused asynchronous clash run for the next batch.	`operationId: string` [required] `batchSize: integer` [default=0] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_run_status`	Returns progress and per-test outcomes for an asynchronous clash run. Read-only and bypasses host_busy.	`operationId: string` [required] `waitSeconds: integer` [default=0] `waitForCompletion: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`cancel_clash_run`	Requests cooperative cancellation of an asynchronous clash run. It bypasses host_busy. A currently executing native Navisworks test finishes first; no later test is started.	`operationId: string` [required] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NavisHelper

What it does

Example prompts

Requirements

Installation

Configuration

Available tools

Core model, selection, visibility, and viewpoints

Startup and host lifecycle

Selection reports and exports

Model color schemes

Search-and-selection workflow

Clash tests, results, reports, and viewpoints

Clash isolation and screenshots

Clash root matrix

Clash workflows from saved sets

Reusable MCP scenarios

Status and limitations

License

About

Releases

Packages

Contributors

Languages

Tool	Description	Parameters
`selection_property_report`	Returns a structured property report for the current Navisworks selection. Read-only replacement for UI/Excel property quick reports.	`itemLimit: integer` [default=100] `propertyLimitPerItem: integer` [default=1000] `rowLimit: integer` [default=10000] `includeInternalNames: boolean` [default=false] `includeEmptyValues: boolean` [default=false] `categoryFilters: array` [default=null] `propertyFilters: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_export_properties`	Exports the current Navisworks selection property report to an explicit CSV or XLSX file path. Defaults to dry-run; pass apply=true to write.	`outputPath: string` [required] `format: string` [default="csv"] `apply: boolean` [default=false] `overwrite: boolean` [default=false] `itemLimit: integer` [default=100] `propertyLimitPerItem: integer` [default=1000] `rowLimit: integer` [default=10000] `includeInternalNames: boolean` [default=false] `includeEmptyValues: boolean` [default=false] `categoryFilters: array` [default=null] `propertyFilters: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_distinct_property_values`	Returns distinct property values in the current Navisworks selection with counts. Read-only helper for reporting and future color_by_property workflows.	`itemLimit: integer` [default=100] `valueLimit: integer` [default=1000] `includeEmptyValues: boolean` [default=false] `categoryFilters: array` [default=null] `propertyFilters: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`selection_color_by_property`	Colors the current Navisworks selection by the first matching property value. Defaults to dry-run; pass apply=true to write permanent color overrides.	`apply: boolean` [default=false] `itemLimit: integer` [default=100] `groupLimit: integer` [default=1000] `transparency: number/null` [default=null] `includeEmptyValues: boolean` [default=false] `categoryFilters: array` [default=null] `propertyFilters: array` [default=null] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]

Tool	Description	Parameters
`clash_isolate_result`	Previews and optionally isolates one existing Clash Detective result by resultHandle. Can highlight A/B, clip around the clash point or item bounds, hide everything except the pair, choose a preset or custom camera, and optionally capture a screenshot. Defaults to dry-run.	`resultHandle: string` [required] `boxMode: string` [default="point"] `boxOffsetMm: number` [default=1000] `useSectionBox: boolean` [default=true] `isolatePair: boolean` [default=false] `useContextTransparency: boolean` [default=false] `contextTransparency: number` [default=0.7] `colorAHex: string` [default=""] `colorBHex: string` [default=""] `cameraMode: string` [default="current"] `cameraPosition: object{x:number, y:number, z:number}` [default=null] `cameraTarget: object{x:number, y:number, z:number}` [default=null] `cameraUp: object{x:number, y:number, z:number}` [default=null] `projection: string` [default="current"] `screenshotPath: string` [default=""] `screenshotProfile: string` [default="compact"] `screenshotFormat: string` [default=""] `screenshotMaxWidth: integer/null` [default=null] `screenshotMaxHeight: integer/null` [default=null] `screenshotJpegQuality: integer/null` [default=null] `overwriteScreenshot: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`clash_reset_isolation`	Restores the viewpoint, section box, appearance overrides, and temporary visibility changed by clash_isolate_result in the active document. Defaults to dry-run.	`apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]
`capture_current_view`	Captures the current Navisworks view exactly as displayed. Use after clash_isolate_result or after manually choosing any camera angle. Defaults to dry-run.	`outputPath: string` [required] `screenshotProfile: string` [default="compact"] `screenshotFormat: string` [default=""] `screenshotMaxWidth: integer/null` [default=null] `screenshotMaxHeight: integer/null` [default=null] `screenshotJpegQuality: integer/null` [default=null] `overwrite: boolean` [default=false] `apply: boolean` [default=false] `instanceId: string` [default=""] `navisworksVersion: string` [default=""]

Tool	Description	Parameters
`scenario_capabilities`	Returns supported scenario schema versions, complete tool allowlist, contract versions, reviewed writes, safe output projections, parameter/$stepResult syntax, foreach rules, pair-name grammar, and a complete valid example. Read-only.	None.
`list_scenarios`	Lists user-approved NavisHelper scenarios from the current Windows profile. Returns metadata and bounded context-match suggestions only; it never executes scenario steps.	`query: string` [default=""] `navisworksVersion: string` [default=""] `rootFileNames: array` [default=null] `projectLabel: string` [default=""] `limit: integer` [default=3]
`get_scenario`	Reads one saved NavisHelper scenario by scenario_id. This is read-only and does not resolve parameters or execute any step.	`scenarioId: string` [required]
`save_scenario`	Validates and saves a user-approved NavisHelper schema v1/v2 scenario under %APPDATA%\NavisHelper\Scenarios. Defaults to preview. Use {"$parameter":"name"}; schema v2 also supports allowlisted {"$stepResult":"step.output"}, bounded foreach, typed parameters, and per-tool reviewedWrites. stepId must match ^[A-Za-z][A-Za-z0-9_]{0,63}$. Call scenario_capabilities for the full grammar and example. Never store apply/confirm flags, handles, instance/document IDs, credentials, or raw transcripts.	scenario: object{schemaVersion:integer, executionMode:string/null, name:string/null, description:string/null, context:object{navisworksVersions:array/null, rootFilePatterns:array/null, projectLabel:string/null}/null, parameters:array/null, steps:array/null, exactReplay:object{fixedParameters:object/null, contextPolicy:string/null, writePolicy:string/null, safetyEnvelope:object/null}/null} [required] scenarioId: string [default=""] expectedSha256: string [default=""] apply: boolean [default=false] confirmSave: boolean [default=false] confirmExactReplay: boolean [default=false]
`delete_scenario`	Deletes exactly one saved NavisHelper scenario. Defaults to preview and uses SHA-256 optimistic concurrency. It never recursively deletes the scenario directory.	`scenarioId: string` [required] `expectedSha256: string` [default=""] `apply: boolean` [default=false] `confirmDelete: boolean` [default=false]
`resolve_scenario`	Resolves a saved scenario into ordered existing MCP tool calls without executing them. For template mode, show the plan and obtain normal apply confirmation. For exactReplay, a direct user replay request is current authorization: follow agent_instruction, run each preview, enforce the saved safety envelope, then apply without follow-up questions; stop on the first mismatch.	`scenarioId: string` [required] `parameterValues: object` [default=null] `executionIntent: string` [default="preview"] `navisworksVersion: string` [default=""] `rootFileNames: array` [default=null] `projectLabel: string` [default=""]

Folders and files

Latest commit

History

Repository files navigation

NavisHelper

What it does

Example prompts

Requirements

Installation

Configuration

Available tools

Core model, selection, visibility, and viewpoints

Startup and host lifecycle

Selection reports and exports

Model color schemes

Search-and-selection workflow

Clash tests, results, reports, and viewpoints

Clash isolation and screenshots

Clash root matrix

Clash workflows from saved sets

Reusable MCP scenarios

Status and limitations

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages