Statamic Mcp Laravel Package

Getting Started

This package exposes your Statamic site to MCP clients (Claude Desktop, Cursor, etc.) so an agent can read and write entries, terms and globals. Start by confirming the version you install is v3.2.1 or later — anything earlier cannot update a record that holds a date inside a grid, replicator or group (see Gotchas).

1. Install the package into the Statamic app you want to drive, and publish its config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Register the MCP server with your client and point it at the site. Use a local/staging site first — the tools write real content.
3. Give the agent the smallest useful surface: one collection, or one set of entries. Scope API credentials/tokens to that.
4. First use case: ask the agent to read a target entry, echo the current date fields back to you, then change one non-date field. That confirms the round-trip before you trust it with scheduling data.

Where to look first:

• The config file — collections/blueprints exposed, and which tools are enabled.
• The tool descriptions the package registers; they are the agent's only documentation, so read them as carefully as you'd read an API schema.
• Your blueprints, specifically every type: date field: note its format (save format) and whether it's a range (mode: range) or a {date, time} object.

Implementation Patterns

Read-before-write. Agents hallucinate field shapes. Make "fetch the entry, inspect the JSON, then send a minimal partial update" the standard prompt. The package sends what you give it; a full replacement payload is how you lose data.

Send dates as ISO 8601 Zulu. 2026-06-01T10:00:00Z is unambiguous and lands as an instant. If you send a wall-clock string, it is read in the app timezone (config('app.timezone')) and converted to UTC. Both work from v3.2.1; Zulu is the safer default when the agent doesn't know the site's timezone.

Nested dates are now first-class. A prices grid on a programme entry with a valid_from date, or a {date, time} pair inside a replicator set, can be updated — including all the other fields on that entry in the same call. Before v3.2.1, the presence of one nested date blocked every update to that record, regardless of what changed.

Agent workflow that holds up:

1. list/get to locate the entry and capture the exact structure.
2. Compute the change in the agent's reasoning, not in a prompt string.
3. Partial update with only the changed keys.
4. Re-read and diff against the pre-write snapshot; assert untouched date fields are byte-identical.

Test in a fixed timezone. Run the app in UTC for CI, but add one staging pass with APP_TIMEZONE=Europe/Copenhagen (or your real zone) and a date inside a grid. The old bug was invisible under UTC because app-timezone and UTC wall clocks coincided.

Range fields (mode: range, {start, end}) at the top level are writable as of v3.2.1 — pass both keys. Anything still on an earlier release will silently replace the pair with today's date and then throw array_key_exists(): Argument #2 must be of type array.

Unix timestamp fields (format: U) validate and round-trip as integers from v3.2.1. Keep them integers; don't let an agent stringify them.

Gotchas and Tips

• Pin >=3.2.1. On earlier versions, any entry with a date inside a grid, replicator or group is effectively read-only: every update, however unrelated, fails "Not a valid date". If your programme/room content uses a prices grid with valid_from, you cannot write to it at all.
• The old timezone shift is gone — but only in v3.2.1. Prior versions formatted the app-timezone wall clock with a literal Z, so 2026-06-01 10:00 sent to a Copenhagen site was stored as 12:00. If you have data written by an older version, audit date values for an offset equal to your UTC delta before trusting them.
• Save format vs. submit format. Statamic validates against the submitted format (ISO 8601 Zulu, or Y-m-d when the save format has no time) but stores the field's save format (Y-m-d H:i by default). If you customise a blueprint's date save format, verify the package's conversion still matches it — a mismatch shows up as a validation error, not a silent corruption.
• Don't retry a failed date write blindly. The pre-3.2.1 failure was deterministic per-record, not transient. A retry loop just multiplies failed requests against a record the package can't convert.
• Debug by comparing stored vs. sent. When a date looks wrong, read the entry back and compare the raw stored string to what you sent. If the stored value differs by a whole-hour offset, you're on a pre-3.2.1 build. If it errors with "Not a valid date", check whether the field is nested — that's the #64 signature.
• Extension point: the date conversion happens centrally at the package level, not per-blueprint. If you have custom fieldtypes that wrap dates, they won't be converted — surface their values as plain ISO strings and validate on your side.
• Guardrails worth adding on your end: a before/after snapshot diff around agent-driven writes, and a hard refusal to write to entries whose blueprint you haven't explicitly validated the agent against. The package validates dates and shape; it does not know your editorial rules.
• Regression test to keep: create a collection with a grid containing a date field, update a non-date field on it, and assert the date is unchanged — once under UTC and once under a non-UTC APP_TIMEZONE. That single test would have caught every bug in this release.