Skip to main content

First Session

This page walks through one complete loop: connect a target, read the document, make a harmless edit, undo it, then make a real edit and save it on purpose. The same loop is what your agent should repeat for every task.

1. Connect the builder tab​

With the MCP server registered in your harness:

  1. Log into WordPress and open the Etch builder for the page or template you want to edit.
  2. Enable AI Connector in Etch if the builder asks for it, then click AI Connector. The tab dials out to the local connector - nothing is exposed to the internet.
  3. Ask your agent to list targets and pick yours:
etch_list_targets        → shows every connected builder tab
etch_select_target       → e.g. targetId "etch-base"

Each target carries its URL, title, and a heartbeat. The selected target is the working target for all following tools.

2. Recall Project Memory​

Before any status check or editing, the agent should call:

etch_recall_project_memory

On a brand-new site this returns an empty brief. From the second session on, it returns the Project Digest (a short narrative of the project's purpose, conventions, recent work, and open threads) plus a record Brief of stored facts. This is what makes sessions continuous instead of amnesiac. See Daily Workflow.

3. Read before writing​

etch_get_status          → Etch availability, runtime, unsaved-changes state
etch_get_document_tree   → the full block tree with ids
etch_get_selected_block  → whatever you have selected in the builder

Reading never changes anything. The tree gives the agent the block ids every later edit needs.

4. A harmless edit, then undo​

Ask for something visible but trivial - for example, re-apply a heading's current text. Under the hood the agent calls etch_update_block with the block's current text: a content no-op that still exercises the buffered edit path and the history stack. Then:

etch_undo                → walks the document back
etch_get_status          → post-undo health check

The edit was buffered: it appeared in the open builder document, but nothing was saved. If you had closed the tab instead, WordPress would be untouched.

5. A real edit, reviewed, then saved​

  1. Ask for the actual change - a section rebuilt, new blocks inserted, a style adjusted. Block, style, and loop tools all land in the buffered document.
  2. Review it in the Etch builder tab like any hand-made edit. Ask for etch_undo (repeatable) or further edits as needed.
  3. When you are happy, say so. Only then does the agent call:
etch_save_document

Saving is always explicit. No tool in the buffered-edit class saves on its own, and the agent should never call save without your approval.

What persists without saving​

Not everything is buffered. These tool classes write to the database immediately when called:

  • Global stylesheets (etch_create_stylesheet, etch_update_stylesheet, etch_append_stylesheet, etch_delete_stylesheet, etch_add_custom_media)
  • Components (etch_upsert_agent_component, etch_delete_agent_component, etch_save_component_edit_mode)
  • Custom fields (field groups, fields, and field values)
  • Project Memory (remember, correct, forget, digest writes)

If an agent's plan involves these, expect changes to stick right away rather than waiting for a save.

Safety rails to know​

  • Unsaved-changes guard. Switching to another post or template (etch_open_post, etch_open_template) is refused while buffered changes exist; save or undo first.
  • No credentials. The agent never asks for your WordPress login. Your authenticated browser tab is the only credential, and the agent reaches it only through the connector.
  • One agent per target. Two agents editing the same builder tab will collide; keep one mutating agent per target.
  • Typed payloads. Block, style, component, and loop inputs are validated against the official Etch public API schemas before they reach the builder - malformed input returns a structured error in the same response instead of corrupting the document.