[nicholasgower]

What this adds

scripts/hookshot_mcp.py, a Model Context Protocol server that turns a built Hookshot into
something a test can drive. It is a separate Python process: nothing is linked into hookshot.exe, and it needs no game
files of its own.

• launch starts the game headless, muted, on Vulkan, script-only (no physical pad, keyboard or mouse), with its own run
  folder, save folder and shader/pipeline cache.
• press / stick / sequence write the game's existing live-input file (HOS_INPUT_LIVE) and wait for the game to log
  that it read the line.
• screenshot asks the renderer for one PNG of the next presented frame (Vulkan RX_VK_SHOT_FILE, WebGPU
  RX_SCREENSHOT_FILE) and returns it inline as MCP image content plus a path on disk, with the present number.
• status / logs / wait read the process state and the recent game log, and advance wall time.
• stop asks the game to quit with the !quit live command, then terminates if it does not.
• Resources: hookshot://log, hookshot://last-screenshot, hookshot://status.

Game-side seams added for this: HOS_INPUT_SCRIPT_ONLY, the analog stick tokens LX=, LY=, RX=, RY=, the !quit
live command, HOOKSHOT_NO_ENV_FILE, and the one-shot screenshot request files.

Docs: docs/mcp.md (install, host configuration, tools, launch options, what the server sets, limits). The tool and
resource tables in it are checked against the live server by tests/test_docs.py.

Why this matters for testing

Today the project has two testing speeds: game-free unit tests that run in seconds, and a person playing the game. Anything
in between — start the game, reach the title, open a menu, look at the frame — is done by hand, one run at a time, and
cannot be repeated after a change.

That is the gap this closes:

• Regressions can be found without playing. A change to the renderer, the HLE runtime, input routing or the builder
  can be checked by the same scripted sequence: it either produces the expected frames or it does not. The log, the input
  lines and the PNGs are left in a run folder to compare.
• It is the base for every further automated test. Input plus a screenshot plus a log is enough to test menus,
  cutscenes, the pause and file menus, resolution and frame-generation settings, controller mappings and save paths
  without a human at the keyboard.
• Any MCP host can run the test, including agents. Claude Desktop, OpenCode, the MCP Inspector or a CI wrapper speak the
  same protocol; the tools are plain JSON calls and the frame comes back as an image, so "is the title screen drawn?" is a
  question a model can actually answer about a real build.
• It unblocks dependent work. The save editor (feat: add standalone save editor and read-only diagnostics #784) needs scripted input to reach a save point; it is on hold until
  this lands.
• It is cheap to keep running. One process, no window, ~10 GB, a clean exit code, and no dialog boxes anywhere.

Rebased, and the previous PR

This is the same branch as #764, which was closed to keep the queue clear with "please rebase on current main and reopen".
It is now rebased onto main at b2765ba (v2.0.6 and the merges after it), and the game has been rebuilt from this branch
and driven end to end.

What I tested

Not only the unit tests: the server was run against a real build of this branch, over its real stdio transport, and every
tool was exercised. Build: a normal builder layout (hookshot.exe launcher, bin\, romfs), Vulkan back end, Windows,
13 min 47 s, 0 failed modules, 100.0000% of 17,646,501 instructions translated.

Game-free suite (what CI runs):

Check	Result
tests/test_mcp_server.py	PASS — protocol in memory and over stdio, tool and resource catalogue, input-line encoding, environment handling, game_dir, fake-game end to end
tests/test_docs.py	PASS — links, documented commands, MCP tables checked against the live server
tests/test_pr_check.py	PASS
scripts/pr_check.py --base main	PASS — 19 changed paths, none forbidden; LF endings; Conventional subjects and both trailers

The full game-free suite gave 107 passed, 5 failed, 11 skipped. The five failures need tools this PC does not have — Vulkan
and SPIR-V headers, the Windows SDK headers for this compiler, and symlink privileges — and none of them touch a file in this
PR. The three new checks above pass.

Every tool against the real game, over stdio (34 checks):

Tool	What was verified
launch	cold run reached its first present at 85 s while 38,809 programs were prepared, warm run ~4 s; pid, run dir, log, input and request paths returned; wait_ready works
status	correct before launch, while running (renderer Vulkan (hookshot_vk.dll), uptime, last screenshot) and after stop
screenshot	1280x720 PNG inline and to a chosen path, present parsed (e.g. "present 116"); the picture is the presented frame
press	A acknowledged in the game log, and it started New Game — the frame changed from the title screen to the intro cutscene
stick	left and right acknowledged; LX=, LY=, RX= in the log; the frame changed
sequence	a three-step line queued and acknowledged (0:DOWN/120,400:DOWN/120,800:A/150); the frame changed
wait	returns status; uptime advances
logs	filtered (hid: live) and unfiltered; every injected line appears
stop	clean !quit, exit code 0, process gone; a second stop is safe
resources	status (JSON), log (text/plain), last-screenshot (image/png, 1280x720)
error paths	before launch, duplicate launch, unknown button, centred stick, reserved extra_env, after stop — all clear messages

The visual half of that run was checked too: title screen, then the cutscene after A, then further changes after stick and
sequence — 12/12 visual checks. One detail worth knowing (now in the docs): the very first wait_ready screenshot of a cold
run is a black boot frame, because it returns on the first present while the shaders are still being prepared; the run above
waited for the title before asserting on the picture. The screenshots stayed on the development disk; no game-derived file is
in this PR.

Finally the server was installed as a project MCP server in OpenCode (V2 mcp.servers configuration) and the nine tools were
called through OpenCode itself — status, launch (with wait_ready), wait, press, stick, sequence, screenshot,
logs, stop — all returned the expected results, and the run ended with exit code 0.

Bug found and fixed by this testing

--game-dir and HOOKSHOT_MCP_GAME_DIR selected the folder's hookshot.exe. In a folder made by the builder or
make_game.py that is the setup launcher, which opens the installed builder (builder/setup/setup.c), not the game in
bin\; launch would have started the builder setup and no screenshot would ever have arrived. resolve_paths now prefers
bin\hookshot.exe and falls back to the top of the folder for a development build, and tests/test_mcp_server.py covers
both layouts.

docs/mcp.md also now gives the V2 OpenCode configuration (mcp.servers, no enabled field) and notes that wait_ready
returns on the first present, which on a cold cache is a boot frame while the shaders are still being prepared.

On the CLI-first feedback in #764

The points raised there — a CLI, files instead of inline images, state in run folders, waits on game state, a GPU lock — are
reasonable, and this keeps the door open for them. Every tool is a thin call into GameSession; the run state already lives
in a run folder (log.txt, input.txt, shot.request, shots/); screenshot(inline=false) returns a path instead of image
content; and input waits for the game's acknowledgement line rather than a fixed sleep. A CLI front end over the same
functions, a wait-on-log-state tool and a GPU lock are the natural next steps, and none of them need this PR to change shape.

Settings and the cheat menu (added since this PR opened)

• settings() reads every row of the Insert menu — Graphics, Gameplay and Controls — with its key, label, value, range
  and the text the player sees. When the cheat menu is on it also returns the Cheats page's eleven rows, the pouch's
  items, the 31 teleport destinations and the inventory's 85 items with their counts.
• set_setting(name, value) goes through the menu's own setter: it clamps, applies a quality preset or a control layout,
  marks the settings Custom and writes hookshot_options.ini. A row that says it needs a restart still does.
• cheat(name, value, item) runs a cheat row directly: heart protection, no-clip flight and the free camera; mark and
  return; the clock; teleports by name or index; the age; the pouch; the inventory (a wanted count, or -1 to
  unlock/relock).
• launch(cheats=true) turns the cheat menu on with HOS_OOT_CHEATS=1, which is otherwise a line in hookshot_env.txt
  before start.

On the game side these are three live-input commands — !settings, !setting <key> <value>, !cheat <name> <value> <extra> — answered in the game log, which the server reads back. The rows cross the renderer table (API 8) from
gpu/vk/vk_menu.cpp through host/rx_backend.c to host/nn_hid.c. The WebGPU back end has no Insert menu and says so.

Testing found and fixed one real defect: two cheat actions in quick succession overwrote each other (the menu kept a single
atomic), so an inventory edit sent right after a pouch edit was lost. They are a queue now, and both are taken.

Real-game verification against a build of this branch (Vulkan, a copied save): 23 settings listed with ranges and text;
set_setting("frame_pacing", 1), set_setting("text_speed", 3) and set_setting("frame_generation", 0) applied, shown by
settings() and written to hookshot_options.ini; an unknown key refused; heart protection and the free camera toggled
and read back; cheat("set_time", 18) made the game log "cheats: requested 18:00"; cheat("pouch", item="Bombs", value=5)
logged "cheats: pouch Item_Bomb +5"; cheat("teleport", item="Kakariko Village") moved Link from Death Mountain Trail to
Kakariko Village (screenshot, and "cheats: teleport child to KakarikoVillage_Child ... request sent"); mark_position
logged the position; two actions sent back to back both ran.

The game-free suite: 134 passed, 11 failed, 14 skipped — the same eleven environment failures as origin/main in a
clean worktree.

Not included

No game files, dumps, builds, saves, logs or screenshots. Test runs stayed under work/, which is ignored.

[hckrman101]

Hi! This PR has merge conflicts with main now (a lot has landed today). Could you merge main in or rebase and resolve them? Happy to give it a proper review once it's up to date.