Agents and MCP

Wonderpress was built with AI agents as first-class operators. Every command runs headless, output is available as a structured JSON envelope, and the whole authoring model (manifests as source of truth, generated code checked for drift) means an agent can create and maintain components through the same contract a human uses.

What init sets up

wonderpress init writes, at the environment root:

  • AGENTS.md: the project’s conventions plus a live index of its manifests. This is the document an agent reads to learn what exists and how to work here.
  • CLAUDE.md: one line, pointing at AGENTS.md.
  • MCP host configs for four hosts: .mcp.json (Claude Code), .cursor/mcp.json, .vscode/mcp.json, and .codex/config.toml.

Open the environment root in Cursor, Claude Code, VS Code, or Codex and enable the wonderpress MCP server when the host asks. The first write of a host config prints how to enable it (Cursor gets an install deeplink; Claude Code approves when you run claude; Codex after you trust the folder).

wonderpress agents write

Regenerates all of the above. It runs automatically after init, partial create, partial sync, and template create; run it yourself after inventing components by hand. Do not hand-edit the generated AGENTS.md index.

Two details worth understanding:

  • MCP configs are gitignored (agents write adds the ignore rules). They pin this machine’s Node binary (process.execPath), the absolute path to the CLI’s bin/wonderpress.js, and cwd set to the environment root, so the host cannot substitute its own Node. Those paths are per-machine, so the files stay out of the repository. AGENTS.md and CLAUDE.md are committed.
  • An existing wonderpress MCP entry is left alone. Hosts tie their “trust this server” approval to the config contents, so rewriting a working entry forces everyone to re-approve. Pass --force after switching Node versions or moving the checkout, then re-approve once.

Install the CLI with a native Node for your machine; process.arch should match the CPU.

wonderpress mcp

Starts an MCP stdio server inside the CLI package. Tools call the same operations as the CLI: partial_list, partial_create, partial_sync, lint_theme, and the rest. wonderpress mcp help lists them.

Boundaries, on purpose:

  • init, destroy, server, acf install, and static compile are not tools. Environment lifecycle and watch-mode processes stay with humans.
  • Destructive tools (removes) require confirm: true.
  • lint_theme with fix: true runs phpcbf (the CLI’s --fix); it needs no confirm and does not repair drift, which stays partial_sync‘s job.

Machine-readable output

For scripting outside MCP, --format json on version, lint, acf install, static compile (without --watch), partial list, partial check-drift, partial sync --dry-run, and agents write prints exactly one envelope on stdout:

code
{ "ok": true, "data": {}, "error": null }

Exit codes are 0 success, 1 failure, 2 usage. Unknown --format values are refused rather than guessed at.

The agent workflow in practice

An agent working in a Wonderpress project reads AGENTS.md, then works manifest-first: create partials with partial_create (or --json specs), edit manifest JSON for field changes, run partial_sync to regenerate, and let lint_theme plus partial check-drift verify nothing was hand-edited out of agreement. The same drift checks run in CI, so an agent’s work and a human’s work are held to the same contract.