Boot a BBC Micro session. Returns {"session_id": "..."}.

The returned session_id is required by every subsequent tool that operates on this BBC.

model selects the BBC variant. Accepted values are b (BBC B, default), master (Master 128 with MOS 3.20), mos35 (Master 128 with MOS 3.50), and compact (Master Compact). disc is an optional path to a disc image, mounted into drive 0 at runtime and SHIFT+BREAK autobooted. The disc is mounted read-only; for writeable or host-mutating mounts call load_disc directly.

Disc-image format follows from the model: BBC B and the two Master 128 variants read DFS images (.ssd and .dsd); Master Compact reads ADFS images (.adl and .adf). The fork's loaddisc accepts all four extensions; the BBC's filing system on the other side reads what it understands.

Mount a disc image into the named drive at runtime.

Drives are 0 or 1 (the BBC has two physical drives in its matrix; beebjit exposes both). writeable cuts the write-protect notch so the BBC can write to the in-memory image; mutable flushes those writes back to the host file. mutable requires writeable. Both default false: the disc is read-only and the host file is never modified.

The mount does not trigger a reset or autoboot: the BBC keeps its current state and the new disc is available for the next OS read. Use boot_disc for the mount + SHIFT+BREAK autoboot one-shot, or compose load_disc with reset(autoboot=True).

Mount a disc and SHIFT+BREAK autoboot it in one call.

Equivalent to load_disc followed by reset(autoboot=True), bundled so the common "load and run" workflow is a single tool call. Same parameters as load_disc. The gesture matches a real user holding SHIFT and pressing BREAK on a running BBC after inserting a disc; the running BBC's state is otherwise preserved through the soft reset.

Blocks until the boot banner reappears in MODE 7 screen RAM, so the call returns with the disc's !BOOT already running (or already finished).

Tear down a session and release its beebjit subprocess.

Returns {"ok": False} if the session id is not recognised; this is not an error because double-destroy on client error is common and should not crash the server.

Hard-reset the BBC without destroying the session.

Equivalent to a user pressing BREAK on the real keyboard. With autoboot=True, holds SHIFT across the BREAK so an inserted disc's !BOOT runs after reset (the BBC equivalent of SHIFT+BREAK). The session_id stays valid; subsequent tool calls hit the same session.

Advance the emulator by cycles BBC cycles.

Returns the number of cycles just consumed plus the total cycle count so the client can track session progress without a separate read_registers round trip.

Run in chunks until prompt appears at the start of a MODE 7 row.

Convenience wrapper for the common "wait for BASIC to return to the > prompt" pattern. Differs from run_until_text by anchoring the match to the beginning of a row: a bare > mid-line (e.g. inside the typed command itself) does not count. Defaults to ">" which is the standard BBC BASIC prompt. Returns {"ok", "found", "cycles_ran", "prompt"}.

Run in chunks until needle appears anywhere in the MODE 7 screen.

Substring match across the entire decoded screen, joined with newlines, so the match is not row-anchored. Use run_until_prompt when the marker must sit at the start of a row (the BASIC > prompt typically does). Returns early as soon as the text is found, or with found=False once max_cycles has elapsed without a match. The chunk size trades responsiveness (shorter = checks more often) against overhead (shorter = more memory reads). Returns {"ok", "found", "cycles_ran"}.

Type an ASCII string into the BBC keyboard.

Uses the default keypress timings (HOLD=5M, GAP=5M BBC cycles). Use \n to submit a line. Lowercase letters arrive as uppercase under the cold-boot CAPS LOCK ON default; use type_input_raw (after set_caps_lock(session_id, False)) when case must be preserved. Raises via the underlying UnsupportedCharError if the string contains a character with no BBC matrix mapping. Returns {"ok": True, "chars": N}.

Type a BBC BASIC program, RUN it, and return the final screen.

Convenience wrapper around type_input + cycle runs. program is the full BASIC source; each line must carry its own line number (this tool does not auto-number). A leading NEW is issued first so the program runs in a clean workspace.

boot_cycles gives BASIC time to reach the prompt after NEW; settle_cycles is the max BBC cycle budget for the program's own execution after RUN.

Returns the MODE 7 screen as rows (list of 25 lines) and text (newline-joined) so callers can assert on either shape.

Type an ASCII string, preserving case.

Requires CAPS LOCK to be OFF. Call set_caps_lock(session_id, False) first if the session is at its cold-boot default of CAPS LOCK ON. Case mismatches produce the wrong letter; no silent fallback.

Inject a raw BBC keydown event into the matrix.

key is either a symbolic name ("A", "CAPS_LOCK", "LEFT_ARROW", ...) or an integer key code. Single-character ASCII strings ("A") are accepted and treated as the corresponding matrix position; everything longer goes through SPECIAL_KEYS. The press stays held until a matching key_up; callers that want a tap should use type_input instead, which handles the HOLD/GAP timing.

Tap CAPS LOCK once to toggle the current state.

A pure toggle: the tool does not know or care about the pre-tap state. Use set_caps_lock(session_id, on) if you need a deterministic final state; that tool reads the MOS caps-lock flag and presses only if needed.

Set CAPS LOCK to a specific state, tapping only if needed.

Reads &025A to learn the current MOS CAPS LOCK state, taps key 135 once iff the current state differs from on. Returns the resulting state and whether a tap was issued, so callers can assert the final state without a follow-up read_memory.

Inject a raw BBC keyup event into the matrix.

Inverse of key_down. Accepts the same key formats. Sending "RELEASE_ALL" (code 255) clears every held key in one call.

Poke bytes into memory starting at addr.

data is a hex string. Optional whitespace between bytes is tolerated, so "4269AB" and "42 69 AB" both write the same three bytes. Symmetric to read_memory, whose hex field can be round-tripped back in here.

Peek length bytes starting at addr. Returns hex and ASCII views.

Dot-substitution in the ASCII view (non-printable -> .) is the convention a human already expects from hexdump and similar tools.

Disassemble count 6502 instructions starting at addr.

Returns a list of {addr, info, text} dicts. info is beebjit's per-line tag ("ITRP", "JIT", sometimes empty); text is the mnemonic and operands. count is capped at 20 (beebjit's native batch size); for a longer disassembly loop by advancing to the address past the last instruction.

Return 6502 register state.

Returns a dict with keys A, X, Y, S, PC, cycles as integers, and F as an 8-character flag string from beebjit's debugger (each flag position shows an upper-case letter when set, a space otherwise).

Capture the MODE 7 screen as 25 rows of teletext text.

controls selects how non-printable bytes render:

• "space" (default): single space, every row stays exactly 40 characters wide. Best for substring assertions and any caller that indexes into rows by column.

• "question": single ?, every row stays exactly 40 characters wide. Useful when callers want non-printable cells visually distinct without decoding the byte value.

• "escape": four-character \xNN escape per non-printable byte. Row widths become variable; use when callers need the original byte value preserved in the decoded string.

JSON callers send these as the literal strings; Pydantic coerces them to Mode7Controls members before this function runs, and rejects unknown values at the wire boundary.

Returns both the raw row list and a \n-joined single string so callers can use whichever view they prefer.

Capture the current rendered BBC screen as a PNG.

Returns an MCP image content block carrying the PNG bytes. MCP clients that recognise image content (Claude Desktop, Claude Code, Cursor, and so on) render the screenshot natively and can save it via their own file tools. Width and height are available from the PNG header (8 bytes after the IHDR marker) for callers that need them. Works in any BBC display mode: beebjit does the rendering, this tool just packages the result. Requires a fork binary that supports -headless-render and the savescreen debugger command; older binaries surface a structured error pointing at the install docs.

Reload a pure beebjit_mcp module without restarting the server.

Intended for in-session development: edit keyboard.py or screen.py, call this tool, and the next tool call picks up the change. Only the pure (IO-free) modules are supported; reloading driver or server would invalidate live session objects and is rejected.