# Vantage Code Mode MCP Server

The Vantage Code Mode MCP Server lets Claude, Codex,
Gemini, and other LLM clients work with Vantage: inspect and modify
scene state, open and save files, probe and modify properties of scene
objects, and run VScript payloads through the Scratchpad.

The LLM client sees named tools such as `vantage_status`, `vantage_scene_inventory`,
and `vantage_eval`, plus Code Mode's `execute` tool for multi-step work.

## Walking along a request path, from Server config to request's end

| Stage | What happens |
|---:|---|
| 1 | The modified Vantage installer installs the MCP server runtime and writes managed MCP entries for Claude, Codex, and Gemini. |
| 2 | Vantage is already running and exposes its native bridge. When an LLM needs it, the MCP client starts `Vantage-MCP-Server.exe --stdio`. |
| 3 | Before tools become available, MCP lifespan asks the bridge to load the minimal MCP-owned VScript when needed and waits for VScript readiness. Bridge, bootstrap, or readiness failure aborts the connection. |
| 4 | After that gate, MCP initialization supplies the stable Vantage/VScript operating model; the client can read targeted `vantage://reference/...` resources when an exact member or value shape matters. |
| 5 | The MCP server turns a tool call into a compact JSON bridge request. Code Mode can wrap several tool calls in one Python `execute` step. |
| 6 | The bridge request goes over the native Win32 named pipe with explicit framing, readiness checks, payload guards, and structured pacing for racing control. |
| 7 | The native bridge receives the command inside the running Vantage process. |
| 8 | App-level operations use `LavinaApp`: status reads, scene-load tasks, `.vantage` saves, script loading, and quit requests. |
| 9 | VScript eval uses `VScriptManager::executeAdHocSnippet(...)` through Vantage's Scratchpad path, with captured output, result values, errors, and scene-change metadata. |
| 10 | Utility helpers such as `vantage_scene_inventory` and `vantage_object_probe` collapse common discovery work into one structured call. |
| 11 | Large results, such as 10k scene instances plus metadata, return through chunked native response frames, are reassembled in Python, then reduced to counts, samples, hashes, or filtered subsets before the LLM sees them. |

That is the whole shape: MCP client, installed server, VScript-aware tools, pipe
transport, Vantage-side execution, VScript/helpers, and a controlled response
path back to the model.

## Install and client setup

The modified Vantage installer owns the setup. Client machines do not need Python, pip,
virtual environments, PyInstaller, or a source checkout.

| Piece | Owner |
|---|---|
| Runtime payload | Vantage installer |
| Claude config entry | Vantage installer |
| Codex config entry | Vantage installer |
| Gemini config entry | Vantage installer |
| MCP server launch | The MCP client, through `--stdio` |
| Manual diagnostics | `--ping` and `--wait-bridge-ready` |

You normally do not run the helper commands by hand. Install and uninstall are
installer hooks. `--stdio` is launched by the MCP client when an LLM uses
Vantage MCP.

A first stdio connection is deliberately strict: Vantage must already expose
the native bridge, and the server must establish a ready VScript before FastMCP
serves tools or callbacks. Successful MCP status calls therefore run after that
readiness proof. Standalone `--diagnose` reads raw native status and may observe
the pre-bootstrap `scriptingEnabled` or `vscriptLoaded` flags instead.

## Knowledge up front, references on demand

Agents do not have to guess the Vantage surface from memory or spend the hot
path rediscovering its basic rules. The MCP initialization instructions include
the stable VScript execution model, scene collections, object lookup rules,
write-proof protocol, value-shape rules, and canonical failure tokens.

```text
vantage://reference/index
vantage://reference/vscript-surface/camera/fov
vantage://reference/return-values/Vector.v
```

Those MCP resources provide deterministic routing and exact SDK facts without
creating another domain tool or duplicating VScript as a typed mutation API.
Code Mode can use the same direct tools inside `execute`:

```python
await call_tool(name, params)
```

Use direct tools for direct actions. Use Code Mode when the agent needs loops,
polling, retries, filtering, hashes, or several Vantage calls before returning a
small final value. Code Mode orchestrates VScript; it does not replace it.

## Pipe and protocol

The pipe is the strong local transport under the MCP server.

| Behavior | Why it matters |
|---|---|
| Native bridge readiness is a chain: process, ready event, then ping/status. | The ready event alone is treated as a hint, not proof. |
| MCP connection readiness additionally requires a ready VScript. | The server loads the minimal bootstrap when needed and aborts startup if bridge, bootstrap, or readiness fails. |
| Requests are length-prefixed JSON frames. | Python and native code agree on explicit frame boundaries. |
| Request frames have a `64 MiB` JSON guard. | Oversized requests are rejected before accidental whole-buffer JSON allocation. |
| Responses up to `64 MiB` use one frame. | Ordinary responses stay simple. |
| Larger responses are chunked. | Big native results can return without pretending the pipe frame is infinite. |
| Chunk reassembly is validated and capped at `2 GiB`. | Ordering, encoding, final flags, base64 data, and aggregate allocation are checked. |
| Raw pipe races can return `BridgePipeBusy`. | The one native pipe instance is serving or recycling; that is pacing, not a scene failure. |

The native bridge currently passes `1 MiB` as the advisory input and output
buffer size to `CreateNamedPipeW`. Windows owns the actual pipe-buffer
allocation and backpressure behavior. That advisory setting is not the protocol
frame size.

## Vantage-side execution

Vantage owns the scene, renderer, and VScript runtime. Apart from `ping`,
commands are posted back onto the Vantage app thread before they touch host
state.

`LavinaApp` is used for app-level work: `get_status` reads async app state and
scene/script flags, `open_scene` enqueues Vantage's normal scene-load task,
`save_scene_as` calls the product `.vantage` save entry point, `open_script`
uses Vantage's script loader, and `request_quit` follows the normal main-window
close path.

VScript eval is narrower. After the bridge gets the interactive core from
`LavinaApp`, it fetches the scene's `VScriptManager` and runs
`VScriptManager::executeAdHocSnippet(...)` through Vantage's Scratchpad path.
The Scratchpad boundary supplies the MCP-owned `mcpSceneObj` alias from the
loaded script's engine-owned scene object, so reads do not replace a running
behavior script. Loaded script files themselves define `MyLogic`; VScript calls
its constructor with `sceneObj`.
The MCP result includes structured fields for success/failure, stdout, stderr,
result capture, errors, and whether the scene changed.

The helper tools are there to avoid waste. For example,
`vantage_scene_inventory` can return counts plus sampled cameras, lights, and
nodes in one call. That saves the agent from making a chain of ad-hoc VScript
queries and from dumping a full production scene into chat just to answer a
small question.

## Tool and reference surface

| Area | Tool | What it is for |
|---|---|---|
| Bridge | `vantage_status` | Runtime state, scene-load state, scripting state, and VScript readiness. |
| Bridge | `vantage_ping` | Cheap bridge health check. |
| Bridge | `vantage_start` | Start the installed one-up Vantage for recovery after an established MCP session loses its host. |
| Scene | `vantage_open_scene` | Open a `.vrscene` through Vantage. |
| Scene | `vantage_save_scene_as` | Save a `.vantage` wrapper. |
| Discovery | `vantage_scene_inventory` | Return normalized camera/light/node counts and sampled entries. |
| Discovery | `vantage_object_probe` | Inspect the live VScript surface of one camera, light, or node. |
| VScript | `vantage_open_script` | Load a Python script into Vantage's VScript runtime. |
| VScript | `vantage_eval` | Run ad-hoc VScript and capture structured output. |
| VScript | `vantage_eval_json` | Run VScript and parse a marked JSON result server-side. |
| Session | `vantage_quit` | Close Vantage through its normal Save/Discard/Cancel path. |
| Code Mode | `execute` | Run async Python orchestration around Vantage tool calls. |
| Code Mode | `tags`, `search`, `get_schema` | Compact tool discovery for the Code Mode surface. |

Vantage reference material is exposed as MCP resources rooted at
`vantage://reference/index`, including deterministic routing, VScript surface
members, and return-value shapes. `get_schema` belongs only to Code Mode's
compact discovery surface; there is no duplicate `vantage_get_schema` tool.

Mechanically provable failures return a small structural envelope with a stable
failure token, evidence, next action, and—when useful—the targeted reference
URI. The server does not keep a catalog of task recipes or model-specific
mistakes; the LLM remains responsible for authoring the VScript.

`vantage_quit` follows Vantage's normal dirty-scene prompt. The no-prompt
shutdown command is kept for development and is not exposed as an LLM-facing
tool.

`vantage_start` cannot rescue the first connection when Vantage is absent:
lifespan must succeed before any tool can be called. It remains useful after an
established server session loses Vantage because the MCP process stays alive
and can launch the installed one-up executable with Home skipped.

## Large responses without context flooding

The bridge can move large local payloads, but the MCP layer should return
compact answers. A 10,000-node scene may have enough names and metadata to be
large on the wire; the useful answer may only need counts, hashes, samples, or a
filtered subset.

That is the intended path:

```text
Vantage data -> native response chunks -> Python reassembly -> helper summary -> compact LLM answer
```

The latest stress report (below) measured large payload bodies inside tools and returned
byte counts, lengths, hashes, timings, and samples instead of raw bodies. The
reported visible token cost for the full stress ledger was low: `407` estimated
LLM input tokens and `1,039` estimated output tokens.

## Stress evidence

The latest recorded live battery passed `29 / 29` checks against an open
Vantage instance.

| Signal | Result |
|---|---:|
| Installed runtime live against open Vantage | PASS |
| Vantage host process + native ready event | PASS |
| Scene probe | 10,000 nodes, 1 light, 1 camera |
| Full node-list representation | 478,898 chars in 0.053 s |
| Largest Code Mode payload | 1,024 MiB in 16.637 s |
| 1,024 MiB effective rate | 61.6 MiB/s |
| Code Mode timeout | Did not trip; 1 GiB completed under 60 s |
| Public MCP concurrency | 400 / 400 served |
| Raw VScript race pacing | 43 served, 257 `BridgePipeBusy`, 0 `BridgeUnavailable` |
| Final bridge health | PASS, VScript OKScript |
| Estimated LLM tokens, all reported rows | 407 in / 1,039 out |

## Repository notes

| File | Purpose |
|---|---|
| `REPOSITORY.md` | Builder-facing release, packaging, patch, and verification details. |
| `END_USER_README.md` | Installed-user notes copied into the frozen runtime. |
| `stress-test-results.md` | Latest live load-test evidence. |