# Vectorworks MCP Codex Plugin

Lean Codex plugin for the latest [vectorworks-mcp](https://github.com/BhaveshY/vectorworks-mcp) runtime. The plugin packages skills, a stable control helper, and companion launch scripts; the MCP engine, listener, tests, and native SDK source remain in the companion repository so they cannot drift into a stale embedded copy.

This plugin is strictly Windows 11-only and requires Vectorworks 2024 or 2025
on the same desktop. macOS, Linux, WSL, containers, Wine, and cross-machine
bridge layouts are unsupported.

## Install

```text
/plugin marketplace add BhaveshY/vectorworks-mcp-codex-plugin
/plugin install vectorworks@vectorworks-mcp-codex-plugin
```

Run `vectorworksctl agent-install --json` once to resolve or clone the companion
to `%USERPROFILE%\repos\vectorworks-mcp`, prepare its cached `.venv`, and return
the exact loader and next steps. Daily MCP startup only resolves an existing
checkout and validates its companion contract; it never clones the repository
or runs the full setup flow. Missing or stale checkouts therefore fail fast
with a repair command instead of delaying MCP connection. The companion runner
still checks its requirements stamp and repairs a missing or outdated virtual
environment; running `agent-install` first keeps that work off the normal path.

Recommended explicit override:

```powershell
$env:VW_MCP_REPO = "C:\path\to\vectorworks-mcp"
```

Use `vectorworksctl agent-install --json` for initial setup and
`vectorworksctl doctor --json` for troubleshooting. For daily work, Codex
should begin with `vw_agent_context(profile="production")`, which combines
preflight, capabilities, and compact drawing context in one MCP call.

## Safety model

- Native phase 2 is the preferred non-modal production path.
- The Python `dialog` listener is a usable CAD-safe fallback while its dialog
  remains open.
- Background/timer listeners are transport-only and must not execute CAD calls.
- Destructive, probing, and trusted-code tools require their explicit live
  confirmation arguments.

Supported application target: Vectorworks 2024/2025 on native Windows 11 only.