> 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. # 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. 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 --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](https://www.mcpdelta.com/docs/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: 1. It reads an object and renders it as text. 2. It parses that text and plans the write. 3. 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 ` runs the check. `--enable` serves a connector as documents for the kinds that passed, and `--disable` goes back to programs. See [The text form](https://www.mcpdelta.com/docs/cli-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](https://www.mcpdelta.com/docs/three-tools). 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.