Contributing to scry-mame

This page is for changing the server: where the code lives, which checks a change must pass, and what proves it. What the tools promise is in REFERENCE.md.

Where the code lives

The checks

Shell
$ uv run ruff check .$ uv run mypy --strict .$ uv run mypy --strict --platform win32 .$ uv run pytest -q$ bash .githooks/pre-commit-test.sh

All five pass before a change is committed. What each one proves:

The tests run with a home and a temporary folder of their own, and fail a run that leaves a file in that home (scry-core's private_run). Every file the server writes follows scry-core's rule of file names; a red names_judged means one was written outside it.

On Windows the fourth command is uv run pytest -q --no-cov. The coverage floor is checked on macOS only, because Windows skips the cases that need what it lacks (a FIFO, a mode bit, a symlink).

.github/workflows/ci.yml runs the same checks on GitHub's Linux runners when started by hand, with --no-cov and with jscpd installed for the hook. The tests need a lua on the PATH and, on Linux, lsof; the workflow installs both.

Running part of the tests

Every pytest run checks the coverage floor, which belongs to the whole repository, so a partial run fails on it. Two traps follow from how addopts is written:

The Lua the server sends

The Lua the server sends MAME lives in src/scry_mame/lua/. lua_source.py loads it and fills each __SCRY_<name>__ slot with a Lua literal of its value's type.

tests/test_lua_scripts.py checks every script as it is sent, with three programs, and fails when one is missing: StyLua (stylua --check), luac of Lua 5.4, which is MAME's, and luacheck. On macOS, brew install stylua luacheck lua@5.4. Windows skips that file: the scripts are the same bytes there.

A scry-core checkout

uv run syncs the environment before its command. So the next plain uv run replaces an editable install of a scry-core checkout (uv pip install -e ../scry-core) with the pinned package. The run then checks the pinned package while looking like a run on the checkout.

Changing a tool

A tool's reply model is its contract:

The tests refuse an ok reply that lacks a required field. tests/test_reply_models.py refuses a promised field whose condition the sentence does not say.

A change to a tool's arguments, reply model or description changes its reference page. tests/test_reference_pages.py then fails, naming the tool, the page and the line. Rewrite the pages from the code:

Shell
$ uv run python -m scry_core.reference scry_mame.server:REFERENCE --write

Every sentence of an entry is in docs/reference/asks.json, one object per tool. It holds what the tool does, its example's ask, a sentence per argument and per field, what it refuses and why. The registry gives the rest.

The examples are calls of the tour, docs/reference/tour/tour.py: one session on Gridlee that calls each tool once, with every reply checked.

Shell
$ uv run python docs/reference/tour/tour.py --rompath <the folder of gridlee.zip> --display 1$ uv run python -m scry_core.reference scry_mame.server:REFERENCE --write \$     --examples docs/reference/tour/TRANSCRIPT.md demos/*/TRANSCRIPT.md

To replace one of those, add that run's transcript.jsonl to --examples. Each --mark spells one of that computer's directories the way the committed examples do: --mark '/tmp/<the run>=$TMPDIR'.

A promise in the reference has a test that fails against the defect it guards. The parsers of MAME's console are tested on text captured from a real MAME, never written by hand. The captures are under tests/fixtures/console/, and tests/fixtures/README.md says where each came from.

A tool that moves to another group

An entry is found by its tool's name, so it moves with the tool. Change the tool's group in src/scry_mame/mcp.py, then rewrite the pages: its block leaves one page and lands on the other.

The line of each group in asks.json, the paragraphs of REFERENCE.md that name the group, and the demos' tables of tools need the same pass. The group of each tool both servers have is roster.SHARED_FAMILIES in scry-core.

The commit hook

The commit runs scry-core's pre-commit check; python -m scry_core.hook --help says what it looks at. Turn it on once per clone:

Shell
$ git config core.hooksPath .githooks

One of its checks is the share of comments and docstrings in each file's bytes. A change that only deletes code raises that share and can fail with no comment touched. Cut a clause in the file it names; never raise the limit.

Tests against a real emulator

A plain pytest starts no emulator. These two scripts do, and both call every tool through the server:

Shell
$ uv run python tests/live/live_check.py$ timeout 1800 uv run python tests/live/live_matrix.py

live_check.py runs its checks on games this repository does not carry and on the demos' free ROMs, with the MAME that MAME_BINARY names. A game it needs and does not find makes the run INVALID, naming what is missing.

live_matrix.py tries every tool in every state of the machine, at every edge of its arguments, and every pair of tools that share state. It prints one line per test case:

What the scripts read from the environment:

Variable What it sets
MAME_BINARY the MAME the free ROMs and the V30 games run on, built with every driver
MAME_TEST_ROMS the directory of the free ROMs
MAME_LIVE_BENCH the folder of the private test games, each with its own MAME where it needs one
LINEUP_MAME_ROMS, SPEEDF_MAME_ROMS each game demo's ROM set and symbol map
MAME_LIVE_SECTIONS the letters of the sections to run; unset, all of them
MAME_LIVE_JOBS how many sections run at once, each as its own process; unset, half the CPUs
MAME_BACKGROUND 1 opens every window behind, 0 every one in front; unset, each start decides
SCRY_FOCUS_CONTROL 1 lets the focus section open a window in front and move a Space

With a variable unset, the cases that need it are BLOCKED and name it. The tracked test code names the private games only by a label; a set name MAME publishes may appear.

A few cases depend on the computer:

What a window opened behind promises

A start behind does not come to the front, so the keyboard stays where it was. That is all it promises: the window is still there to be seen, and the computer carries the load of every emulator the run starts.

So run the live test script in an account or on a machine nobody is working at, or at an hour agreed with whoever is. Whether a run took the front is the focus section's verdict, read as scry-core's page on these tests says.

A game controller makes a debug MAME abort

A debug build of MAME aborts at start, on an SDL3 input assert, while a game controller is connected. Every start of these tests passes an ini that holds joystickprovider none as inipath: the tracked tests/live/fixtures/ini-no-joystick, or a copy. A start written by hand passes one too.

What a run checks about the computer

A run refuses a computer that cannot start MAME, and proves it left none running (scry_core.live_host):

Demos

demos/<name>/demo.py runs one demo end to end. With --update-readme it rewrites the demo's page from a run where every step passed: the two generated blocks of its README, TRANSCRIPT.md, screen.png and loop.webp.

The block of the README that adds the server to each client is scry-core's table of clients:

Shell
$ uv run python -m scry_core.install scry_mame --write

The description test

A tool's description, its arguments and the server's instructions are all a model has to call the tool from. The description test gives a model only what a client delivers and checks the calls it makes:

Shell
$ uv run python -m scry_core.probe mame --servers mcp_probe/servers.py \$     --tasks mcp_probe/tasks --check$ uv run python -m scry_core.probe mame --servers mcp_probe/servers.py \$     --tasks mcp_probe/tasks --runs 3

A task the model keeps getting wrong is tolerated when the server refuses the wrong call and says why: report it with its numbers. A client retries on a refusal, and more description text spends the room the other tools need. Only a wrong call the server accepts with status: ok is a defect.