Storefront agent (MCP)

The storefront agent is an internal MCP server, storefront, built on laravel/mcp (platform plan, phase E). An AI agent such as Claude Code can use it to:

read a shop’s storefront and catalogue;
change its profile, theme, theme settings, home page sections and images;
preview the draft, publish it, and revert to an earlier version.

Same rules as Settings → Storefront. Every write goes through StorefrontConfig with the same all-or-nothing validation, and lands in the draft. The single exception is occasion tags, which are catalogue data and go live at once. Changes are recorded in the version history with source mcp and the operator label MCP_ACTOR.

Running it

It speaks MCP over stdio and has no web endpoint (routes/ai.php, Mcp::local). Using it needs the same access as running artisan on that machine.

Local development. .mcp.json registers it next to Laravel Boost, so Claude Code in this repository can use it at once:

"flowery-storefront": {
    "type": "stdio",
    "command": "php",
    "args": ["artisan", "mcp:start", "storefront"],
    "env": { "MCP_ACTOR": "claude (local)" }
}

Production, over SSH (from a machine with the chat-ui SSH alias):

It reads and writes the live shops, so an agent can publish a real storefront.
Its instructions require it to show the preview and get agreement first.

"flowery-storefront-production": {
    "type": "stdio",
    "command": "ssh",
    "args": ["chat-ui", "cd ~/flowery.com.ua/current && MCP_ACTOR='claude (alex)' php8.4 artisan mcp:start storefront"]
}

Tools

Each tool except the first two takes shop, the shop’s address (batata for batata.flowery.com.ua). The tool enters that shop as the tenant, so every query is scoped to it.

Tool	What it does
`list-shops`	Shops with their published theme and version, and whether the draft has unpublished changes
`list-themes`, `describe-theme`	Themes, and a theme’s settings and section types with types, bounds, options and maximum counts; the profile fields and link rules
`get-storefront`	The draft, the published version, and the paths where they differ
`get-catalogue`	Categories, visible bouquets (price, availability label, occasions, photo), flowers, packaging and occasions in use. Read-only
`list-versions`	Published versions: who, when, from where, and the note
`set-theme`, `update-settings`	Switch theme; change theme-wide settings
`update-profile`	Tagline, about, contacts, hours (merged day by day), links, delivery note, default language
`update-sections`, `update-section`, `add-section`, `remove-section`	The home page: reorder, show or hide, change, add and remove sections
`set-image`	The logo, a theme setting or a section image, from `bouquet:<id>` or an https URL downloaded safely (public hosts only, JPEG, PNG or WebP up to 5 MB; `SafeImageDownloader`) into the shop’s own storage
`tag-bouquet-occasions`	A bouquet’s occasions (live at once)
`preview-url`	A one-hour link showing the draft
`publish`	Make the draft live as a new numbered version, with a note
`revert`	Copy an earlier version into the draft

Rules the agent is given

The server’s instructions, which every client receives:

Edit the draft, show preview-url, and publish only after the owner agrees.
Never invent: no reviews, ratings, awards, guarantees, delivery times, popularity claims or facts about the shop. Write only what the owner said or what the shop’s data shows. Delivery promises go in the profile’s delivery note, in the owner’s words.
Write in the shop’s language (Ukrainian unless told otherwise), as plain text.
Use only images the shop owns or may use.
Prices, stock, orders and product names and descriptions are out of scope; they belong in the control panel.

Checks

Feature tests. tests/Feature/Mcp/StorefrontServerTest.php calls each tool through the server. It covers:
- Unknown shops and themes.
- Tenant scoping: another shop’s bouquets are refused in sections, images and occasions.
- All-or-nothing validation errors.
- The day-by-day hours merge.
- Draft against published.
- Publish with the operator label, and revert.
Stdio smoke test. On 5 October 2026, php artisan mcp:start storefront answered initialize (with its instructions), tools/list (all 18 tools, read-only hints) and a list-shops call. The server lists every tool on one page, because some clients do not follow tools/list pagination: laravel/mcp returns 15 per page by default.