MCP tools

Every tool takes workspace and project. Paths are relative to the project's root, use /, and may not leave the project. Ignored paths behave as if they did not exist. Your client can also list the tools with their full JSON Schemas (tools/list).

A tool that fails returns an MCP error result whose text says why: a bad argument, a missing file, a stale version, a held lock, or a limit. Errors carry a structured code and message.

Reading

read

Read a text file from the main worldline, optionally a range of lines. Long files are cut at the project's read_max_lines and read_max_bytes; ask for a later range with offset.

Argument	Type
path	string
offset	integer, optional	First line, 1-based.
limit	integer, optional	Number of lines.

Returns content, first_line, lines (returned), total_lines, truncated (more lines follow) and version.

list

List files, optionally under a directory (prefix). Returns files (each a path and size), truncated and version, at most list_max_entries entries.

glob

Find files by path pattern: * and ? within a directory name, ** across directories (src/**/*.cpp). Takes pattern; returns files, truncated and version.

search

Search text files for lines containing a string.

Argument	Type
query	string	Text to find.
regex	boolean, optional	Treat query as an ECMAScript regular expression.
files	string, optional	Only files matching this path pattern.

Returns matches (each a path, 1-based line and the line's text), truncated and version, at most search_max_matches.

Changing files

write, edit, remove and move change the project's main worldline. Each requires the :: lock: call worldline with action: "lock" and scopes: ["::"] first.

Each accepts an optional operation_id. Sending the same ID and input again returns the recorded result (replayed: true); the same ID with different input is refused with identity_conflict. The result carries the new version, the receipt and the operation_id.

write

Create a file, or replace its whole content. Takes path and content.

edit

Replace text in a file. old_string must occur exactly once unless replace_all is set.

Argument	Type
path	string
old_string	string, exactly as in the file
new_string	string
replace_all	boolean, optional

The result also carries replacements.

remove

Delete a file. Takes path.

move

Rename or move a file. Takes from and to (which must not exist).

Recovering a file-tool result

Use the worldline tool with action: "receipt", worldline: "main" and the same operation_id. It returns the recorded version, receipt and manifest. It never sends the change again.

Generating source

generate

Preview or create files from a template. action is catalog (the templates and their parameters), preview (the default; renders files without writing) or apply. parameters has template_id and name, and optionally package, standard, directory and sample (whether to add sample code).

apply needs the :: lock and an operation_id. Existing files are never overwritten.

Worldlines

worldline

Fork, lock, read, edit, inspect, revert and recover isolated worldlines. Takes an action and the arguments that action needs; see Worldlines for each action.

The main actions are list, inspect, read, fork, lock, unlock, locks, apply, receipt, history, reverse and redo. Reads use version; writes use observed and a durable operation_id.

Building and running

tools/list is the schema source for these tools. Each accepts worldline and version, so a worker executes exactly the version the caller selected.

configurations

List the project's build and run configurations and the operations each build configuration provides.

build

Build one or more configurations at once: sync the selected version to a worker, execute its build steps, and return steps, output and compiler diagnostics.

Argument	Type
configurations	string array, optional; defaults, or ["*"] for all
targets	string array, optional
worldline	string, optional; main when absent
version	string, optional; the current one when absent

test

Run the test operation and its dependencies. Takes configurations, filter, labels, worldline and version, and returns steps, diagnostics, output and a test summary when CTest output is available.

run

Invoke a saved run configuration. Takes configuration, configurations, worldline and version.

Language

language

Plan, prepare or query language analysis bound to a worldline version.

Argument	Type
worldline	string, optional	main when absent.
version	string, optional	The version to query; the current one when absent.
configuration	string, optional	The analysis configuration; the project's only one when absent.
action	string, optional	plan, prepare, receipt, scopes (default), symbols, definitions, references or diagnostics.
symbol	string, optional	Narrows definitions or references to one symbol.
operation_id	string, optional	For prepare and receipt.

The result names the configuration, the analysis environment, the version, whether the data is stale, and the requested scopes, symbols, references, relations or diagnostics. When no analysis covers the version it reports analyzed: false rather than an empty success.