Randoloot/addons/godot_mcp_toolkit/docs/advanced_configuration.md

# Advanced Configuration

These are **optional fine-tuning knobs** that most users never need to touch —
the defaults are chosen to work well out of the box. They live under
**Project → Project Settings → `mcp_toolkit/`** (enable *Advanced Settings* to
see them) and can also be set with `ProjectSettings`.

Apart from the response limits under **Limits**, whose ranges the dock and the
Project Settings inspector both enforce, none of these values are clamped in
code: the recommended ranges below are guidance, not enforced limits. An extreme
value is allowed and is your responsibility.

## Concurrency

The toolkit serialises editor mutations and arbitrates scene access across
multiple MCP clients. These keys tune that machinery.

### `mcp_toolkit/concurrency/scan_idle_timeout_ms` — default `5000`

How long a scene save or open waits for an in-progress `EditorFileSystem` scan
to finish before giving up, in milliseconds. Opening or saving a scene *during*
a scan can read inconsistent filesystem state and crash the editor, so the
toolkit waits the scan out first and **aborts the operation with a `TIMEOUT`
error** if the scan hasn't settled in time — it never proceeds into an active
scan.

- `0` = fail fast (don't wait at all).
- Recommended `1000`–`30000`.
- Raise it for large projects whose imports take long to scan, at the cost of
  longer save/open stalls when a scan is genuinely stuck.

### `mcp_toolkit/concurrency/mutation_watchdog_grace_ms` — default `60000`

Extra grace, in milliseconds, added to a mutation's deadline before the dispatch
**watchdog** force-clears a wedged mutation lock. The deadline is the in-flight
command's *declared* `timeout_ms` (or the 300 s system maximum for a command
that doesn't declare one) **plus** this grace.

The watchdog is a **safety net**: it only fires if a mutation handler aborts or
hangs and would otherwise block *all* further mutations until the editor
restarts. In normal operation it never fires. Lowering this shortens recovery
from such a (rare) wedge but risks force-clearing a legitimately slow handler;
the generous default makes a false fire effectively impossible for any
well-behaved command.

### `mcp_toolkit/concurrency/scene_lease_ttl_ms` — default `8000`

When multiple clients edit different scenes, a time-bounded *lease* prevents
cross-scene contamination: tab-dependent commands from a non-holding client
queue until the holder's lease expires. This is how long, in milliseconds, the
holder may go without renewing before a waiting client can steal the lease.

- Lower = snappier hand-off between clients, but more tab switching.
- Higher = fewer tab switches, but a waiting client blocks longer.

## Reading large data — caps & the pagination contract

Read tools that can return a large payload are **capped per call** and **paginate**
instead of streaming a whole file in one response (responses are sent whole over a
size-limited WebSocket frame, so an uncapped read would silently drop). Two tools
page today — `save_read` (a `user://` file, in **bytes**) and `script_read` (a
project script, in **lines**) — and they share one **uniform pagination contract**,
so the loop you learn for one applies to the other.

### The uniform pagination contract

On a capped read you always get:

- **`has_more`** (bool) — `true` when more data remains beyond this window,
  `false` when this window reached the end. Always present on a successful read.
- **`total_<unit>`** — the full size of the source (`total_bytes` for `save_read`,
  `total_lines` for `script_read`), so you know how much is left.
- **`returned`** — the size of this window (bytes for `save_read`, lines for
  `script_read`).
- **`next_<cursor>`** — the value to pass back to resume, present **only when
  `has_more` is `true`** (`next_offset` for `save_read`, `next_start_line` for
  `script_read`).
- **`hint`** — a one-line prose instruction, present **only when `has_more` is
  `true`**, telling you exactly which cursor to feed back.

**The loop is always the same:** call the tool; if `has_more` is `true`, pass the
returned `next_<cursor>` back as the matching request parameter and call again;
stop when `has_more` is `false`.

**Worked example — `save_read` (bytes).** Request `offset` (default `0`) +
`max_bytes`; resume with `next_offset`:

```
save_read  path=user://saves/big.dat  max_bytes=400
  → { returned: 400, offset: 0, next_offset: 400,
      total_bytes: 1000, has_more: true,
      hint: "more bytes remain — re-call save.read with offset = next_offset (400) until has_more is false" }
save_read  path=user://saves/big.dat  offset=400  max_bytes=400
  → { returned: 400, next_offset: 800, total_bytes: 1000, has_more: true, hint: … }
save_read  path=user://saves/big.dat  offset=800  max_bytes=400
  → { returned: 200, next_offset: 1000, total_bytes: 1000, has_more: false }   # done — no hint
```

**Worked example — `script_read` (lines).** Request `start_line`/`end_line`
(1-based); resume with `next_start_line`:

```
script_read  file_path=res://big.gd  start_line=1  end_line=200
  → { start_line: 1, end_line: 200, total_lines: 520, returned: 200, has_more: true,
      next_start_line: 201,
      hint: "more lines remain — re-call script.read with start_line = next_start_line (201) until has_more is false" }
script_read  file_path=res://big.gd  start_line=201  end_line=400
  → { start_line: 201, end_line: 400, total_lines: 520, returned: 200, has_more: true, next_start_line: 401, hint: … }
script_read  file_path=res://big.gd  start_line=401  end_line=600
  → { start_line: 401, end_line: 520, total_lines: 520, returned: 120, has_more: false }   # clamped to EOF, done — no hint
```

A **full** `script_read` (no `start_line`) that fits under the cap returns
`has_more: false` and `total_lines` as well, so both read shapes carry the same
fields. The request-parameter names stay unit-appropriate (`offset`/`max_bytes`
for bytes, `start_line`/`end_line` for lines) — only the response *shape* is
uniform.

### When a cap change takes effect (no restart)

The read caps below (`save_read_cap_kb`, `script_read_cap_kb`) are read by the
handler **on every call**, so a change made in the dock, in Project Settings, or by
an `.mcp.json` override applies to the **very next call**, with no restart and no
reconnect. `ws_buffer_kb` is the exception: the editor sizes a connection's buffer
when it accepts the connection, so a change applies from the next connection.

**The server is not pushed the value.** The MCP server advertises a *static*
`max_bytes` schema bound as a sanity ceiling; the **toolkit enforces the real,
live cap at call time**. A request above the live cap is rejected with
`INVALID_PARAMS` whose message names the *current* cap — so if you lower the cap,
the model learns the new limit **reactively from that error**, not from the
advertised schema. (This is why a value that the schema appears to permit can
still be rejected: the live cap is authoritative.)

## Limits

The dock and the Project Settings inspector keep their own edits inside each
limit's range and step. A value set another way, such as an `.mcp.json` override
(given in bytes) or a hand edit of `project.godot`, is used as set (the save cap
still never drops below 64). Both surfaces then show it clamped to the range and
rounded to the nearest step.

### `mcp_toolkit/limits/save_read_cap_kb` — default `256`

The largest window `save_read` returns in a single call, in KB (64–4096, in steps
of 64). A `user://` file bigger than this cap can still be read in full by
paging — see **Reading large data** above for the `offset` / `next_offset` loop.
This is the only way to read a file larger than the WebSocket frame ceiling (see
`ws_buffer_kb` below), because responses are sent whole.

Raising this above `ws_buffer_kb` is a footgun: a window that would not fit the
WebSocket buffer is rejected with `FILE_TOO_LARGE` before it is sent, rather than
silently dropped. If you raise the cap, raise `ws_buffer_kb` to match (and note
the runtime caveat below).

### `mcp_toolkit/limits/script_read_cap_kb` — default `256`

The largest payload `script_read` returns in a single call, in KB (64–4096, in
steps of 64). A project script bigger than this cap is read in full by paging on
**lines** — see **Reading large data** above for the `start_line` /
`next_start_line` loop. A full read that would exceed the cap is rejected with
`FILE_TOO_LARGE` and a hint to use a line range.

If `GODOT_MCP_SCRIPT_READ_LIMIT` is set in `.mcp.json`, it overrides this value:
the MCP server sends it to the editor when it connects, and the dock then shows
it, clamped and rounded to the dock's range and step. The editor keeps it until it
restarts or the value is changed, and the next time project settings are saved, it
is written to `project.godot`.

### `mcp_toolkit/limits/ws_buffer_kb` — default `1024`

WebSocket per-peer buffer size, in KB (256–8192, in steps of 256). Raise it if you
send very large payloads (e.g. big `script_write` bodies) and see truncated or
dropped connections under load.

If `GODOT_MCP_WS_BUFFER_LIMIT` is set in `.mcp.json`, it overrides this value in
the same way, and the dock then shows it, clamped and rounded to the dock's range
and step. The editor sizes a connection's buffer when it accepts the connection,
so the override applies to connections accepted after the server sends it, not to
the connection that sent it.

> **Runtime (exported game) caveat.** This setting tunes the **editor** server
> only. The runtime server that runs inside an exported game uses a **fixed 1 MB
> per-peer buffer** and ignores `ws_buffer_kb`, so raising `ws_buffer_kb` does
> **not** raise the runtime ceiling — page large runtime reads with `save_read`'s
> `offset` instead.

## Listen ports (editor & runtime)

Two of the toolkit's three MCP channels bind a **dynamic** TCP port. By default
each **scans** a small band and publishes the bound port to the machine-wide
registry, so the MCP server discovers it with no configuration. You can instead
**pin** an exact port or **relocate** the scan band, per channel. These are read
from the process environment (the `.mcp.json` `env` block, or a shell `export`
before launch) — the toolkit never writes them.

| Env var | Channel | Effect | Default |
|---|---|---|---|
| `GODOT_MCP_EDITOR_PORT` | Editor channel | **Pin** — bind this exact port or fail | — (scan) |
| `GODOT_MCP_EDITOR_PORT_MIN` / `_MAX` | Editor channel | **Relocate** the scan band (inclusive) | `6550` / `6560` |
| `GODOT_MCP_RUNTIME_PORT` | Runtime channel (the running game) | **Pin** — bind this exact port or fail | — (scan) |
| `GODOT_MCP_RUNTIME_PORT_MIN` / `_MAX` | Runtime channel | **Relocate** the scan band (inclusive) | `6570` / `6585` |

The same `GODOT_MCP_EDITOR_PORT` / `GODOT_MCP_RUNTIME_PORT` are **also read by the
MCP server** to decide which port to **dial** — inherited by both processes, a pin
makes listen and dial agree with zero discovery. The `_MIN`/`_MAX` band vars are
**listen-side only** (the server never reads them; discovery covers the scanned
case). The third channel — the GDScript **LSP** — is Godot's to bind, so it stays
**connect-pin-only** via the server-side `GODOT_MCP_LSP_PORT` / `GODOT_MCP_LSP_HOST`
(next section).

### Pinned vs. Scanned — the two modes are exclusive

- **Pinned** (a `*_PORT` pin is set): the listener binds that **exact** port or
  **fails loudly** — it never scans to a different port. If the port is occupied it
  retries the same port briefly (to ride out a previous instance still releasing
  it), then surfaces a **dock warning** (editor) or a loud game-console error
  (runtime) naming the port. A pin makes the `_MIN`/`_MAX` band **irrelevant** — it
  is ignored (a one-line note is logged).
- **Scanned** (no pin): the listener scans the band (default, or `_MIN`/`_MAX` if
  set), binds the first free port, and publishes it for discovery. This is the
  **low-friction** default — you don't have to manage env on both sides. If the
  **whole band** is occupied, the editor shows the same dock warning naming the
  range and keeps retrying.

A malformed pin, an out-of-range port (valid range `1–65535`), or `MIN > MAX` is a
**clear error** on the dock + console, never a silent fall-back to the default.

### An environment variable is not a sync channel

The editor process (which **listens**) and the MCP server process (which **dials**)
read the environment **independently**. A pin only makes them agree if **both**
processes inherit the **same** value:

- **The normal `.mcp.json` case sets `env` for the server only.** If you also launch
  the Godot editor from a **desktop shortcut**, that shortcut does **not** inherit a
  shell's transient `export` (notably on Windows), so the pin reaches the server but
  not the editor — the server would then dial a port nobody is listening on. It now
  **fails fast** with a precise message instead of hanging (and the editor dock shows
  the mismatch), but the real fix is to make both sides inherit the pin.
- **The supported pattern (harness / parallel tests):** `export` the pin **once**,
  then launch the editor **and** the MCP server/client as children of that same
  environment so both inherit it:

  ```bash
  export GODOT_MCP_EDITOR_PORT=6557
  godot --editor --path /path/to/project &   # editor inherits the pin (listens on 6557)
  # …launch the MCP client from the same shell so its server inherits it too (dials 6557)
  ```

- **Prefer Scanned mode** if you don't want to manage env on both sides — registry
  discovery keeps the two in agreement automatically.

## macOS: launching your MCP client (Node / PATH)

Modern GUI-launched MCP clients — Claude Desktop, VS Code, and Cursor — capture
your login shell's environment and resolve a bare `npx` to a version-manager Node
on their own, so the standard `npx -y @npgamedev/godot-mcp-server` config connects
whether you launch the client from Finder/Dock or a terminal. The toolkit writes
that standard command; there is nothing macOS-specific to configure.

**If a client won't connect on macOS**, work through these:

- **Launch the client from a terminal to see its error.** `open` won't help — start
  the app's binary from a shell. A terminal launch inherits your `PATH` and prints
  the client's real startup error, which tells you what to fix.
- **Confirm `.mcp.json` is present at your project root** and Node 22+ is installed
  (`node --version`). If `.mcp.json` is missing, click **Write .mcp.json** in the
  MCP Toolkit dock.
- **Move your version-manager init into `~/.zprofile`.** If your Node lives behind a
  version manager (nvm/fnm/volta) whose init is only in `~/.zshrc`, a login-shell
  launch won't see it — add it to `~/.zprofile` too so Finder/Dock launches resolve
  Node as well.
- **Zero-config alternative:** install Node from the **official nodejs.org
  installer**. It lands on the default `PATH`, so no shell setup is needed.

**Point a Mac at a local server build** (development) by setting
`GODOT_MCP_DEV_SERVER_PATH` in the environment to your built `dist/index.js` — the
toolkit then emits a `node <that path>` command instead of the released `npx` form.

## Language server (LSP)

The `lsp_*` tools connect to Godot's built-in GDScript language server. The MCP
server discovers the right endpoint per project from the registry, so a **single
editor needs no configuration**. These two env vars (set in a project's
`.mcp.json` `env` block) override discovery — needed only when running the LSP in
**more than one editor at once** (see `docs/multi-instance.md`).

### `GODOT_MCP_LSP_PORT` — default: discovered (else `6005`)

The GDScript LSP port this project's server connects to. Top priority — bypasses
registry discovery. Set it to the `--lsp-port` you launched that editor with.

### `GODOT_MCP_LSP_HOST` — default: discovered (else `127.0.0.1`)

The host for the GDScript LSP. Rarely needed — the LSP is localhost-only. Mirrors
the familiar `lsp.serverHost` client setting.

## Editor responsiveness while unfocused

> **Note — these two keys live in Editor Settings, not Project Settings.**
> Open **Editor → Editor Settings** and search for `mcp_toolkit/performance`.
> Everything else in this document is a *Project* setting; these two are the
> exception, because they control a **machine-global editor behaviour** and are a
> personal battery/CPU preference — so they are deliberately **not** written to
> `project.godot` (never committed to version control).

When the editor loses focus, Godot throttles its process loop to a low-power
frame rate (the `interface/editor/unfocused_low_processor_mode_sleep_usec`
editor setting, ~10 fps by default). The toolkit polls its WebSocket inside that
loop, so an unfocused editor answers MCP commands only ~2–3 times per second.
During a normal MCP session the editor *is* unfocused (you're looking at the chat
window), so the toolkit raises the unfocused frame rate while a client is
connected, then restores it on the last disconnect.

### `mcp_toolkit/performance/keep_editor_responsive_unfocused` — default `true`

Opt-in switch. When **on** (default), the toolkit boosts the unfocused frame rate
while at least one MCP client is connected. When **off**, Godot's default
low-power unfocused throttle is left untouched — choose this if you are
battery/CPU-sensitive and don't mind slower command pickup while the editor sits
in the background. A matching toggle and a live **Off / On (idle) / On · active**
indicator are in the dock's *Server Status* section.

### `mcp_toolkit/performance/unfocused_responsive_sleep_usec` — default `16666`

The boosted unfocused process sleep, in microseconds. Lower = higher frame rate =
snappier commands but more background CPU. Not clamped.

- `16666` ≈ **60 fps** (default) — maximum snappiness; also keeps automated
  smoke/sweep runs fast. Zero behavioural change from earlier toolkit versions.
- `33333` ≈ **30 fps** (power-saver) — roughly half the background CPU. The
  difference is imperceptible to an interactive user (command latency is
  dominated by the agent's thinking time) and adds only ~20–30 s to a full
  automated smoke run.
- The poll loop runs every 4th frame, so the effective MCP poll rate is about a
  quarter of the frame rate (≈15 Hz at 60 fps, ≈7.5 Hz at 30 fps).

> A quick CPU sanity-check on one machine showed an idle editor's background CPU
> at 60 fps vs 30 fps vs the 10 fps default differs only modestly; exact numbers
> are machine-specific, so treat the above as guidance, not a measurement.

### Crash- and concurrency-safety

The boosted value is a machine-global setting, and Godot only flushes editor
settings to disk on certain events (closing the settings dialog, quitting, …), so
a crash *after* such a flush — or a second editor running at the same time —
could otherwise leave the setting stranded at the boosted value. To prevent that:

- Before boosting, the toolkit records the **true original** value once, to a
  small machine-wide, Godot-version-keyed backup file (in the toolkit's registry
  directory — the same place multi-instance discovery uses), under a
  first-writer-wins file lock. A second editor that connects while the first is
  already boosting will **not** overwrite that backup, so the true original is
  never lost.
- On the last disconnect — and again as a **self-heal on the next editor
  startup** — the toolkit reverts the setting **conflict-aware**: if the live
  value still equals the value the toolkit wrote, it is restored to the true
  original; if you (or another tool) changed it in the meantime, **your value is
  kept** and the backup is simply cleared. Either way the boost can never persist
  without a live connection.

**Documented edge cases:**

- If you manually set the key to *exactly* the boosted value while it is already
  boosted, Godot emits no change event (same-value writes are no-ops), so the
  toolkit cannot tell your value from its own — on restore it treats it as its own
  and reverts to the original. This is the single case the conflict-aware check
  cannot detect.
- With two editors connected at once, if the first disconnects it restores the
  setting while the second is still connected, so the second runs at the default
  unfocused rate until its next fresh connection. This is a brief responsiveness
  dip, never a persistent change, and matches the toolkit's earlier behaviour.

---

*These are advanced tunables. If you're not sure, leave the defaults.*