Practice

Four sessions you can copy.

These are the calls that built this site, in the order they ran. Each one is a plain JSON-RPC request; the daemon carries it, the plugin authorises it, WordPress does the work. Nothing here needs a plugin on the client side.

stdio → daemon → REST Basic auth JSON-RPC 2.0

01 · Publish a page

Content tools write immediately and are never transaction-staged. The result carries the new post id, its permalink and an atomicity block.

→ tools/call · agentshell_create_page
{
  "title":   "Capabilities",
  "slug":    "capabilities",
  "status":  "publish",
  "content": "<section class="as-hero">…</section>"
}

← {
  "id": 12,
  "title": "Capabilities",
  "status": "publish",
  "slug": "capabilities",
  "url": "https://flowbyte.com/capabilities/",
  "atomicity": {
    "database_transaction": true,
    "engine": "InnoDB",
    "on_failure": "rolled back",
    "not_covered": ["email", "filesystem", "outbound HTTP"]
  }
}

A titled page with an empty body is valid and gets created. A page with neither a title nor content is refused before anything is written — WordPress would otherwise store an untitled draft that no listing can identify.

02 · Restyle the site, transactionally

Configuration writes are staged. Open a transaction, move tokens, look at the diff, run the doctor, then commit. Until the commit, an ordinary visitor still sees the old site.

→ tools/call · agentshell_begin_transaction
{ "label": "showcase design system" }

→ tools/call · agentshell_set_palette
{ "colors": { "background": "#0e1013", "text": "#e9e7e2", "accent": "#ff7a2f" } }

→ tools/call · agentshell_preview_transaction
← { "added": ["--theme-bg", "--theme-text"], "changed": ["--theme-accent"], "removed": [] }

→ tools/call · agentshell_validate_transaction
← { "errors": [], "warnings": [] }

→ tools/call · agentshell_commit_transaction
← { "committed": true, "revision": 12 }

Preview is isolated. The staged state renders only for a request carrying a short-lived preview credential. Everyone else keeps seeing the committed configuration, so a half-finished restyle never reaches the public.

03 · Edit published content without touching the original

A published post is edited in a private shadow row. The original keeps serving its old content until the publish step commits; the preview credential shows the staged version to the actor who asked for it and to nobody else.

→ tools/call · agentshell_begin_transaction
{ "label": "changelog entry" }

→ tools/call · agentshell_edit_published
{ "post_id": 18, "title": "Changelog", "content": "<section…>" }

→ tools/call · agentshell_screenshot
{ "post_id": 18, "transaction": true, "viewport": "desktop" }
← { "captured": true, "backend": "AGENTSHELL_CHROME_BIN" }

→ tools/call · agentshell_publish_edit
← {
  "state": "publication_settled",
  "reconciliation": {
    "shadow_deleted": "verified",
    "caches_invalidated": "verified",
    "claim_released": "verified",
    "audit_written": "verified"
  }
}

// publish_edit runs the reconciliation tail itself, so a follow-up
   publish_edit_reconcile is refused: "the publication is fully
   settled; nothing to reconcile."

The reconciliation tail runs after the SQL commit, not inside it. If the process dies between the two, a fresh publish_edit_reconcile finishes the job — the crash is recoverable, not fatal.

04 · Roll back a change nobody approved

Open a transaction, stage something you will not approve, look at it, and throw it away. Because configuration was never written, rollback has nothing to undo — and the audit trail records that you considered it.

→ tools/call · agentshell_begin_transaction
{ "label": "an unapproved colour experiment" }

→ tools/call · agentshell_set_palette
{ "colors": { "accent": "#7c3aed" } }

→ tools/call · agentshell_preview_transaction
← { "changed": ["--theme-accent"] }

→ tools/call · agentshell_rollback_transaction
← { "rolled_back": true, "note": "Configuration was never modified." }

The live site is byte-identical afterwards. Verify it yourself with agentshell_get_config or by diffing the revision list.

Wiring

The client side is three lines.

{
  "mcpServers": {
    "agentshell-demo": {
      "command": "php",
      "args": [
        "/home/v/projects/agent-shell-theme/agentshell-mcp-daemon/daemon.php",
        "--config", "/home/v/.agentshell-mcp-demo.json"
      ],
      "exposure": "direct"
    }
  }
}

The daemon config holds the endpoint, the WordPress user and an Application Password, in a file with mode 0600. The daemon adds Basic auth, forwards the message and returns the answer. That is the whole transport.