Skip to main content
Glama
vw-bridge

vw-bridge

by Gribiche64

vw-bridge

MCP server that exposes Vectorworks Spotlight fixture data to Claude Code (or any MCP client). Watches the Lightwright Data Exchange XML file that Vectorworks writes alongside .vwx files, parses it, and serves queries (counts per layer, channels, weights, plot QC).

No manual export step — VW writes the XML automatically whenever focus switches away from VW.

One-time Vectorworks setup

  1. Open any plot in Vectorworks

  2. File ▸ Document Settings ▸ Spotlight Preferences ▸ Lightwright tab

  3. Tick "Use automatic Lightwright Data Exchange"

  4. Save the XML file in the same folder as the .vwx

  5. Move all desired fields (Inst Type, Channel, Universe, Position, Purpose, Color, Weight, Wattage, Unit Number) from "Available Fields" to "Export Fields"

  6. Click Save as default so all future files use this configuration

You don't need to own Lightwright — this is a built-in VW feature that just writes XML.

Related MCP server: fcp-mcp-server

Install

make install   # installs into ~/.config/vw-bridge/venv

Register with Claude Code

From the directory you cloned this repo into:

claude mcp add vw-bridge -- uv run --directory "$(pwd)" python -m vw_bridge.server

Or with an explicit path:

claude mcp add vw-bridge -- uv run --directory /path/to/vectorworks-bridge python -m vw_bridge.server

Tools

Tool

What it does

set_active_file

Point the watcher at a specific .xml (current show)

set_active_plot

Switch by show name (fuzzy match against folder names)

list_plots

List Lightwright XML files under the shows root, newest first

get_active_file

Show watched file + last update timestamp

get_fixture_counts

Counts per fixture type, optional layer filter

get_fixture_summary

Grand totals: count, weight, wattage

get_layers

Per-layer rollup

get_channels

Channel/universe list, filterable

get_equipment_list

Rental-ready rollup

plot_qc

Audit: duplicate channels, missing addresses, unpatched fixtures — see lighting-plot-qc for the full review methodology built on it

get_fixture_details

Full parsed data for one fixture by UID — use before planning a write

find_fixture_of_type

Find a sibling fixture of a given Inst_Type — source Symbol_Name + Wattage for type swaps

write_fixture_patch

Write changes back to VW — emits an LW-style patch the file watcher picks up

Usage in a Claude Code session

You: How many VL3600 IPs do I have on Truss 1?
Claude: [calls get_fixture_counts(layer="Truss 1")] You have 12 VL3600 IPs on Truss 1.

When you make changes in VW and switch focus to Claude Code, the data refreshes automatically.

Development

make dev    # installs dev deps into .venv
make test   # runs pytest
make lint   # runs ruff

Write-back (added 2026-05-19)

The MCP now writes patches directly to the Lightwright Data Exchange XML — Vectorworks' file watcher picks them up and applies the changes. No Lightwright application, no Python-in-VW script required.

Recipe for a fixture type swap:

# 1. Find an existing fixture of the target type (gives you Symbol_Name + Wattage)
target = find_fixture_of_type("Robe iForte LTX")
# {"found": True, "count": 4, "symbol_name": "Robe iForte LTX",
#  "wattage": "1250 W", "sample_uid": "1244.1.1.0.0"}

# 2. Confirm the source fixture
src = get_fixture_details("1246.1.1.0.0")
# {"found": True, "fixture": {"inst_type": "Ayrton EagleStrike", ...}}

# 3. Write the patch
write_fixture_patch([
    {
        "uid": "1246.1.1.0.0",
        "fields": {
            "Inst_Type": target["inst_type"],
            "Symbol_Name": target["symbol_name"],
            "Wattage": target["wattage"],
        },
    }
])

VW will apply the change when it next gains focus: the on-canvas symbol swaps, the data fields update, the watcher refreshes the cache.

Safety: the writer refuses Delete operations, unknown field names, and UIDs not in the current snapshot. It warns (does not refuse) when Inst_Type changes without Wattage — the "frankenfixture" risk where the symbol swaps but the wattage stays stale.

Protocol spec: see PROTOCOL.md for the full reverse-engineered protocol and WRITE_GUIDE.md for the practical write playbook, the LW-vs-VW writer asymmetry, and known constraints (native FS path required for FSEvents, symbol must exist in resource library, etc.).

Available Tools

13 tools
find_fixture_of_typeB

Find an existing fixture of a given Inst_Type, for borrowing Symbol_Name and Wattage.

Returns the first match plus a count of all fixtures of that type. The Symbol_Name and Wattage of the returned fixture are the canonical strings to use when patching another fixture to this type via write_fixture_patch.

Pattern: 'I want UID 1246 to become a Robe iForte LTX. Find me an existing LTX so I can copy its Symbol_Name and Wattage into the patch.'

Inputs: inst_type (required). Returns: object

get_active_fileA

Show which XML file is being watched and when it was last parsed.

Inputs: no named parameters. Returns: object

get_channelsA

Channel + DMX address listing, filterable by layer and/or fixture type.

Includes only patched fixtures. Each entry has channel, dimmer, absolute address, universe, layer, position, inst_type.

Inputs: layer, inst_type, include_old. Returns: object

get_equipment_listB

Rental-style rollup: fixture type, quantity, total wattage.

Sorted by quantity descending. Includes accessories (clamps, gel frames) aggregated separately.

Inputs: include_old. Returns: object

get_fixture_countsA

Counts of each fixture type, optionally scoped to one layer.

By default the "OLD" parking layer is excluded. Pass include_old=True to include it.

Inputs: layer, include_old. Returns: object

get_fixture_detailsA

Return the full parsed data for one fixture by UID (dotted form).

Use before planning a write — the caller usually needs the fixture's current Lightwright_ID (preserved into the patch), current Inst_Type / Symbol_Name / Wattage, and layer / position to confirm it's targeting the right fixture.

Inputs: uid (required). Returns: object

get_fixture_summaryC

Grand totals: fixture count, total wattage, layer count, device-type breakdown.

Inputs: include_old. Returns: object

get_layersC

Per-layer rollup: fixture count, wattage, and unique fixture types.

Inputs: include_old. Returns: object

list_plotsA

List Lightwright XML files under the shows root, newest first.

Each entry has show_folder, xml_path, vwx_path, modified_at. Useful for picking which plot to watch when you have multiple shows open or when set_active_plot returns ambiguous matches.

Inputs: limit. Returns: object

plot_qcC

Audit the plot for common QC issues.

Reports:

  • duplicate channels (same channel value across multiple fixtures)

  • duplicate DMX addresses (same absolute_address across multiple fixtures)

  • unpatched fixtures (no channel and no DMX address)

  • missing positions

  • missing purposes

Inputs: include_old. Returns: object

set_active_fileC

Point the watcher at a Lightwright Data Exchange XML file.

The file is the .xml that Vectorworks writes alongside your .vwx (in the same folder) when "Use automatic Lightwright Data Exchange" is enabled in Spotlight Preferences. It updates whenever you switch focus away from Vectorworks.

Inputs: path (required). Returns: object

set_active_plotA

Switch the active plot by show name (fuzzy-matched against folder names).

Examples: 'Aurora Nova', 'Eternal Sunshine'. Picks the most recently-modified XML in the matching show's folder.

Inputs: show_name (required). Returns: object

write_fixture_patchA

Apply field changes to fixtures via the Lightwright Data Exchange XML.

The MCP writes a Lightwright-style patch directly to the active XML. Vectorworks' file watcher picks it up on focus-in and applies the changes to the drawing — no Lightwright the application required in the loop.

Args: changes: list of dicts, each with: - "uid": dotted UID, e.g. "1246.1.1.0.0" - "fields": dict of XML field name → string value, e.g. {"Inst_Type": "Robe iForte LTX", "Symbol_Name": "Robe iForte LTX", "Wattage": "1250 W"}

Returns dict with: written_to, uids_changed, patch_size_bytes, warnings.

Safety: - Refuses Delete operations (the writer is patch-only; Delete is a separate operation we intentionally don't support). - Refuses unknown field names (catches typos before VW sees them). - Refuses UIDs not in the current snapshot. - Warns (does not refuse) if Inst_Type changes without Wattage — this is the 'frankenfixture' risk: new symbol but stale wattage.

To plan a type swap safely: 1. Call get_fixture_details(uid) to confirm target UID. 2. Call find_fixture_of_type(new_type) to get the correct Symbol_Name and Wattage strings. If count is 0, pre-place a fixture in VW first. 3. Call write_fixture_patch with Inst_Type + Symbol_Name + Wattage in the same change.

Inputs: changes (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions: file selection, plot selection, fixture lookups, aggregations, QC, and patching. The main ambiguity is between set_active_file and set_active_plot, and several get_fixture_* rollups overlap in concept but differ in output shape.

    Naming Consistency4/5

    The naming pattern is largely consistent verb_noun snake_case: set_active_file, get_layers, write_fixture_patch, etc. The outlier is plot_qc, which is noun-abbreviation rather than verb-first, and find_fixture_of_type is slightly more verbose than the others.

    Tool Count5/5

    Thirteen tools is well within the well-scoped range and each tool covers a distinct workflow need: plot selection, multiple read aggregations, fixture detail lookup, QC, and patching. No tool feels redundant or padding the surface.

    Completeness4/5

    The tool set covers the core workflow of selecting a plot, inspecting it at multiple granularities, running QC, and applying field patches. The main intentional gap is no delete or new-fixture creation, but the descriptions provide clear workarounds by pre-placing fixtures in Vectorworks.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Lets Claude work inside an open Vectorworks drawing on macOS, reading and bulk-editing Spotlight lighting devices, checking positions, and exporting channel hookup paperwork. It can also run arbitrary Vectorworks Python, with validated all-or-nothing edits and a tool that undoes exactly the last change.
      14
      53
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users to let an MCP client read, edit, and generate real Final Cut Pro timelines from exported XML or live projects, covering cut detection, markers, roles, transcript-based edits, keyframes, speed ramps, rough cuts, and cross-NLE export.
      -