MCP tools

reportd serves the Model Context Protocol at /mcp (mcp.path), so an agent can design and render reports. Every tool calls the HTTP API as the caller, so roles, locks, the agent policy (agents.publish), the edit log and the audit apply as they do to people. Tool calls are limited by mcp.rateLimitPerMinute (Configuration).

Tool	What it does
list_reports	List reports
get_report	Get a report
get_outline	Get a report's outline
get_language_reference	RFML language reference
list_components	List components
get_sample_data	Get sample data
validate_report	Validate a report
run_tests	Run a report's tests
preview_report	Preview a report
list_data_sources	List data sources
get_data_source	Get a data source
get_report_params	Get a report's parameters
list_environments	List environments
report_history	Report history
edit_report	Edit a report
undo_edit	Undo an edit
put_sample	Write sample data
create_report	Create a report
publish_report	Publish a report
promote_report	Promote a report
rollback_report	Roll back a report

list_reports

Lists every report in the catalog with its id, title and folder.

Read-only, safe to repeat.

No arguments.

get_report

Returns a report's RFML document, its draft revision (pass it to edit_report as baseRevision) and the names of its bundle files (samples, schemas).

Read-only, safe to repeat.

Argument	Type	Required	Description
draft	boolean		Read the draft (true, the default) or the published copy (false). Without a draft, the published copy is used.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.

get_outline

Returns the report's node tree (page templates and body) with ids, types, labels and locks. Use the ids as targets in edit_report.

Read-only, safe to repeat.

Argument	Type	Required	Description
draft	boolean		Read the draft (true, the default) or the published copy (false). Without a draft, the published copy is used.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.

get_language_reference

Without part: how this server works (environments, drafts, edits, publishing) and which schema parts exist. With part: the generated JSON Schema for document, ops, node:<type> (e.g. node:table), library or source-def.

Read-only, safe to repeat.

Argument	Type	Required	Description
part	string		Schema part: document, ops, node:<type>, library or source-def.

list_components

Lists the components the environment's libraries export: each with its library, version, the import that brings it in (add it to the document's imports, e.g. {"from": "library:billing", "version": "^2.1.0", "components": ["remittance-slip"]}) and its definition (description, props schema, slots). With id, also the components the report defines itself and the libraries it imports.

Read-only, safe to repeat.

Argument	Type	Required	Description
draft	boolean		Read the draft (true, the default) or the published copy (false). Without a draft, the published copy is used.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string		Report id, to include the report's own components and imports. Optional.
library	string		Only this library's components.

get_sample_data

Returns the report's sample data files (samples/*.json), keyed by bundle path. The document's data section says which dataset reads which file.

Read-only, safe to repeat.

Argument	Type	Required	Description
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
path	string		One file, e.g. samples/invoice.json. Omit for all of them.

validate_report

Checks the draft (structure, references, expressions against the dataset schemas) and returns RFML diagnostics with codes, node ids and suggested fixes.

Read-only, safe to repeat.

Argument	Type	Required	Description
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.

run_tests

Runs the report's embedded tests (spec §20: inputs plus expect expressions over the rendered result) on the draft, or the published copy with draft false, and the engine compares page snapshots with the approved ones. Returns each test's pass or fail, why it failed (expectations, render diagnostics, snapshots that are new or changed). Use it after edits to check the report still does what its tests say. Approving snapshots is for people, in the designer.

Read-only, safe to repeat.

Argument	Type	Required	Description
draft	boolean		Read the draft (true, the default) or the published copy (false). Without a draft, the published copy is used.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
tests	array of string		Only these tests, by name. Omit for all of them.

preview_report

Lays the report out with its sample data (never live data) and returns the layout model (pages and boxes with node ids), or one page as a PNG image.

Read-only, safe to repeat.

Argument	Type	Required	Description
draft	boolean		Read the draft (true, the default) or the published copy (false). Without a draft, the published copy is used.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
format	layout, png		layout (default) or png.
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
layoutDetail	pages, boxes, text		layout: pages, boxes (default) or text.
page	integer		png: the page to draw (default 1). At least 1.

list_data_sources

Lists the data source catalogue of an environment: each source's name (use it as a dataset's source, e.g. billing.bill@1), description, typed parameters (fill them with the dataset's sourceParams) and output schema. Queries and connection details are never shown.

Read-only, safe to repeat.

Argument	Type	Required	Description
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).

get_data_source

Returns one data source: its parameters, output schema and sample data (never live data or the query).

Read-only, safe to repeat.

Argument	Type	Required	Description
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
name	string	yes	Source name, e.g. billing.bill.
version	string		A version; omit for the latest.

get_report_params

Returns the report's parameters as prompts: types, labels, bound values and the choices of picklists, computed from sample data.

Read-only, safe to repeat.

Argument	Type	Required	Description
draft	boolean		Read the draft (true, the default) or the published copy (false). Without a draft, the published copy is used.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
values	object		Values chosen so far, for cascading picklists.

list_environments

Lists the environments in promotion order, e.g. dev, test, uat, prod.

Read-only, safe to repeat.

No arguments.

report_history

Lists the published versions of a report in one environment, newest first, with commit ids for rollback_report.

Read-only, safe to repeat.

Argument	Type	Required	Description
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.

edit_report

Applies RFML edit operations to the draft as one atomic batch. The batch is rejected (nothing changes) if it touches locked content you may not unlock, or adds errors. Pass the baseRevision you read with get_report; if the draft has moved on, re-read it. Use dryRun to check a batch first.

Changes things.

Argument	Type	Required	Description
baseRevision	integer		The draft revision the ops were written against. Omit to use the current one. At least 0.
dryRun	boolean		Check and report without saving.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
message	string		What the edit does, for the edit log.
ops	array of object	yes	RFML edit operations (spec §21.1), applied atomically. Each has op: insert, remove, move, set, unset, renameId, wrap, unwrap, convert, extractComponent, inlineComponent, setDocument, or for tables insertRows, removeRows, insertColumns, removeColumns, mergeCells or splitCell. get_language_reference with part "ops" gives the full schema.
ops[].op	string	yes	Operation name.

undo_edit

Undoes your most recent edit to the draft that isn't undone yet.

Changes things.

Argument	Type	Required	Description
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.

put_sample

Writes a sample data file into the draft's bundle (samples/<name>.json). Samples are what previews render with.

Changes things, safe to repeat.

Argument	Type	Required	Description
data	any	yes	The JSON sample data.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
path	string	yes	Bundle path under samples/, e.g. samples/invoice.json.

create_report

Creates a new report draft from an RFML document (with rfml "0.1", an id and meta.title) and optional bundle files such as samples/<name>.json and schemas/<name>.json.

Changes things.

Argument	Type	Required	Description
document	object	yes	The RFML document.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
files	object		Bundle files keyed by path (samples/…, schemas/…), each a JSON value.
message	string		For the edit log.

publish_report

Publishes the draft to its environment: resolves its libraries and data sources, validates it (any error blocks), runs its tests (failures block, by default), writes the canonical form and a lockfile, and commits. Agents may need a person's approval; the reply then says the request is pending. Use dryRun to check without publishing.

Changes things, destructive.

Argument	Type	Required	Description
dryRun	boolean		Run every check and report what would be published.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
message	string		Commit message.

promote_report

Copies the published report from one environment to the next (by default the one after from), with the library releases and data source versions its lockfile pins. Refused, with each problem listed, when the next environment can't get one of them. Agents may need a person's approval.

Changes things, destructive.

Argument	Type	Required	Description
from	string		Source environment; defaults to the first.
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.
to	string		Target environment; defaults to the next one.

rollback_report

Republishes an older version (a commit from report_history) as a new version. Agents may need a person's approval.

Changes things, destructive.

Argument	Type	Required	Description
commit	string	yes	The commit to restore, from report_history.
environment	string		Environment name, as list_environments returns. Defaults to the first (the development environment).
id	string	yes	Report id: the document's id, lower-case letters, digits and hyphens.