Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

F0 tool contracts

Purpose

The F0 spike exposes six tools:

  • ce_info
  • process_list
  • process_open
  • memory_read
  • scan_start
  • scan_results

Their machine-readable contracts are in spec/contracts/f0.yaml. This page explains the conventions and the parts that are easy to implement inconsistently.

The contracts are designs, not implementation claims. The server generator will turn them into the tools/list entries: name, description, inputSchema, outputSchema and annotations. Until F0 passes, no tool is implemented or tested.

Contract conventions

TopicRule
JSON Schema2020-12; every object rejects undeclared properties
OutputstructuredContent must match outputSchema; content is a human-readable fallback
AddressesLowercase hex strings with 0x, for example 0x100000000
HandlesOpaque strings such as ph_... and sh_...; never parse them
PIDs and sizesJSON integers; sizes and limits reject negative or zero values
Memory valuesStrings, so an int64 cannot lose precision in JSON
Scan valuesDecimal strings for numeric types; raw text for string scans
Process filtersprocess_list.filter is a case-insensitive substring match
Process namesprocess_open.name is an exact, case-sensitive match
BytesLowercase hex without separators, or standard base64
Paginationnext_cursor is opaque and tied to the query that produced it
ErrorsisError: true with a structured error object; see Errors

process_open accepts exactly one of pid or name; the schema uses oneOf to reject both or neither. name is an exact process name. A name with multiple matches is an error, not an arbitrary choice.

scan_start supports two comparisons in F0: exact and unknown. The other Cheat Engine comparisons are deliberately absent until they are tested, because they imply different value and previous_value semantics. Adding enum values later is backward-compatible; guessing now is not.

scan_start may return state: "running" with a task_id when the tasks extension is active. scan_results then reports progress without inventing partial rows. A short scan may return state: "completed" directly.

Tool summary

ToolInputOutputRead-only
ce_infoNo argumentsServer, Cheat Engine, bridge, Lua and host versionsYes
process_listfilter, limit, cursorprocesses, next_cursorYes
process_openExactly one of pid, nameprocess_handle, PID, name, architectureNo
memory_readprocess_handle, address, size, encodingaddress, size, encoding, dataYes
scan_startProcess handle, value type, comparison, optional value and rangescan_handle, state, count, optional taskNo
scan_resultsscan_handle, cursor, limit, include_valuesState, value type, rows, cursor, totalYes

The annotations in the contract mark only the read-only operations as readOnlyHint: true. process_open and scan_start change server and target state, so they are not read-only even though they do not write target memory.

Limits and failure behavior

ToolLimit or rule
process_list1–1000 rows per page; an unchanged process list keeps a cursor stable
process_openOne process at a time, matching Cheat Engine’s opened-process model
memory_read1 byte–1 MiB per call; no silent truncation
scan_start1–1,000,000 retained results; range and alignment are optional
scan_results1–1000 rows per page; include_values: false returns null values
CursorsInvalid or expired cursors return CE_INVALID_CURSOR
HandlesUnknown or expired handles return CE_HANDLE_EXPIRED
Busy scansscan_results returns CE_SCAN_BUSY rather than partial garbage

A read at an unmapped address returns CE_INVALID_ADDRESS. A target that exits returns CE_PROCESS_CLOSED, and its process and scan handles are invalidated. The bridge may return CE_TIMEOUT if the operation exceeds its deadline; the caller must poll the handle or task before retrying.

Why these choices

Addresses and values are strings. JSON numbers cannot represent every 64-bit address or integer exactly, and a single schema that sometimes returns a number and sometimes a string is harder for an agent to use. Strings are stable across languages and transports.

Handles are opaque. A handle is not a PID and not an address. Clients must not construct one, cache it across a server restart or send it to another server. This is what keeps the MCP layer stateless while Cheat Engine remains stateful.

memory_read has a strict size cap. Returning an unbounded byte array over a local bridge invites memory spikes and truncated results. The cap makes the limit explicit; memory_dump is the tool for large ranges, and it is outside F0.

scan_start does not hide a long scan behind a blocked request. The contract allows a completed result or a task. The client must handle both shapes. F0 may implement the simple completed path first, but the schema already leaves room for the task extension.

Test obligations

The F0 test plan is the acceptance test. The contract adds these obligations:

  1. Validate every successful result against its outputSchema.
  2. Validate that undeclared input properties are rejected.
  3. Exercise process_open with pid only, name only, both and neither.
  4. Exercise scan_start with exact and unknown; reject other comparisons.
  5. Verify that memory_read returns exactly size bytes and never truncates.
  6. Verify that next_cursor is rejected when reused with different arguments.
  7. Verify that include_values: false does not return stale values.
  8. Verify that handles from a restarted server are rejected.

These tests do not exist yet. They are part of the implementation gate, not a claim about the current repository.

Future tools

The remaining 75 curated tools and the generated Lua tools need their own contracts. They must follow the same conventions: opaque handles, string addresses, bounded pages, structured errors and explicit output schemas. Adding a tool must not change an existing tool’s schema within a major version.