Documents

Deep objects, such as a test with steps and actions, read and rewritten as a few lines of text. How it works, and the rule that keeps it safe.

On this page

Some objects nest: a test has steps, a step has actions, an action has checks. For those, Delta MCP can show your AI a few lines of text instead of a tree of data. Your AI rewrites the text. Delta MCP turns the difference into your connector’s own calls.

Documents are a choice you make for each connector. Out of the box, every connector is served through programs, Cerberus included. mcpdelta compile <connector> --enable turns documents on, as below. For a connector with its own adapter, such as Cerberus, no command or setting turns them on: not yet. See Writing a task.

One object, a few lines

This is a ticket, read as a document. The lines under the first one belong to it.

ticket T-1: Login broken
  status=open

Your AI rewrites it. It closes the ticket, adds a label and adds a comment.

ticket T-1: Login broken
  status=closed labels=late
comment "Closed: fixed in 2.3"

The rules are few. A line under a line belongs to it, indented by two more spaces. Values are quoted. Options are key=value. A title follows :. Attributes left out of the header keep their value.

A test case on Cerberus, a test platform, goes three levels deep. The step is at the margin, the action is indented by two, and the check by four.

testcase Folder/DEMO-001: Login with valid credentials
  application=DemoShop status=WORKING priority=1 countries=BE,FR labels=smoke
prop email = text "alice@demo.test" countries=FR
step use="Folder/LIB-001#2": Login as Alice
step: Check the welcome
  click "id=login-btn" if ifElementVisible "id=login-btn" waitBefore=500 // a comment
    verifyElementTextEqual "id=welcome" "Welcome Alice" fatal=no

How your AI changes one

A write call takes whole documents, edits, or rules. They can be mixed in one call.

docs: whole documents, to create one or make it exactly that.
edits: { ref, old, new } on the document as read, like a file editor. old must be found once, unless all is set.
replace: { find, with, in }, a rule over a scope such as a folder. It changes values, not keywords.
delete: the refs to remove. dryRun: true shows the plan only.

Here are the arguments of the write call that turned the first ticket into the second.

{
  edits: [{
    ref: "T-1",
    old: "  status=open\n",
    new: '  status=closed labels=late\ncomment "Closed: fixed in 2.3"\n',
  }],
}

Delta MCP checks everything first and returns all the errors at once, each with its fix. It applies one plan, all or nothing, reads the result back and keeps it in Activity. The answer ends with:

Applied d… · 1 ticket(s) · 2 call(s) · read back: as written ✓

The two calls are update_ticket and add_comment, named as your connector names them. Writing a document back unchanged makes no call at all.

A small change stays small

Delta MCP lines up the old text and the new one the way a diff does. Identical lines are anchored first. A line that only moved is a move, not a delete and a create. The lines between two anchors are paired in order, as edits of each other.

A paired line keeps its identity on the server. Changing one action doesn’t re-create its neighbours.

The rule: only when it changes nothing

Delta MCP uses the text form only when writing it back changes nothing on the server. It checks this on real objects, reading only:

It reads an object and renders it as text.
It parses that text and plans the write.
If the plan holds even one call, that kind of document fails.

A kind of document passes only if every object sampled passes. The default sample is five. One that fails is listed with the difference, never used silently.

From a terminal, mcpdelta compile <connector> runs the check. --enable serves a connector as documents for the kinds that passed, and --disable goes back to programs. See The text form.

Documents pay on deep objects, where lines have lines of their own. For flat records such as tickets, programs usually cost less, and compile says so.

What your AI sees

A connector served as documents gets tools of its own, beside the three. These are the usual five. A connector that runs things, such as Cerberus, adds run.

Tool	What it does
`read`	Reads documents as compact text, several per call.
`find`	Finds where a value is used, grouped by document.
`write`	Changes documents, as above.
`undo`	Reverts a task. It is refused if a document changed since.
`op`	Calls any other tool of the connector as it is.

Nothing is lost: what the documents don’t cover stays reachable through op. Those calls run for real, one after the other, and Delta MCP can’t undo them. With several connectors served as documents, each tool carries the connector’s name, such as cerberus_read.

The connector’s own limits are told up front. If it has no tool to change a posted comment, a write that changes one is refused before any call.

Updated 7 October 2026 Something missing or wrong? Open an issue