AI Integration¶
Badger Commerce uses AI in a few specific places, mostly to help shop operators set up and run a shop. Nothing customer-facing uses an LLM. The pieces are:
| Feature | Where | Model runs | Needs |
|---|---|---|---|
| MCP server | /mcp on the shop domain |
In the operator's own AI client (Claude etc.) | ROLE_MCP + OAuth2 scopes |
| Extension and pipeline prompts | Served through MCP | (guidance text, no model) | — |
| AI image tagging | Media uploads, processed on the worker | OpenAI vision model | ai-image-tagging-enabled + OpenAI key |
| Change requests | Admin → Content → Change requests | Photos tagged as content; drafts written on the worker by Anthropic or OpenAI (change-request-model) |
change-requests-enabled + image tagging + API key |
| Design Brief chat | Admin → Settings → Design brief | Anthropic or OpenAI, server side | ai-enabled + API key |
| AI Menu Generator | Admin → Settings → Menu | Anthropic or OpenAI, server side | ai-enabled + API key |
| JSON Component generator | jsonComponent extension editor | Anthropic, called from the browser | Admin's own Claude API key |
MCP server: run the shop from an AI agent¶
The main AI feature. Each shop exposes a Model Context Protocol
server at /mcp (Spring AI MCP server, stateless transport), so an agent such as Claude Desktop,
Claude Code or a claude.ai connector can administer the shop: products, variants, collections,
pages, menus, media, extensions, branding, taxonomy, orders, fulfilment, cancellations, returns,
refunds, promotions, gift cards, delivery options, subscriptions, customers, inventory, pipelines,
site config, statistics and an ops inbox. Tools come in read / manage* pairs.
- Access is OAuth2 JWT only, with scopes
mcp:read,mcp:writeandmcp:admin. The user needsROLE_MCP, granted on the admin user details page ("AI tool access via Model Context Protocol"). - An agent is only offered the tools its access allows, and tools for restaurant, dining, appointments, marketplace channels and subscriptions only once the shop uses that feature. This keeps every conversation cheaper.
mcp-refund-limit(site config, default0= no extra limit) caps a single refund an agent can issue.- The LLM runs in the client; the platform needs no AI API key for MCP.
See MCP & OAuth2 for the auth flow, tool conventions and testing.
Extension and pipeline prompts¶
Extensions and pipeline processors carry guidance text for agents: BadgerExtension#getAiPrompt(),
getAiPromptOverview(), getAiPromptSections() and getAiPromptSectionContent(code), and
Processor#getAiPrompt(). About 30 extensions (jsonComponent, hero, animationScene,
trendingProducts, featuredProductExtension, emailCaptureExtension, …) and about 17 processors
override them. Agents fetch them through the MCP extensions tool (getSchema,
getPromptSection) and the pipelines tool before configuring something. The prompts are written
in Java; there is no admin UI for editing them.
AI image tagging¶
When an image is uploaded (admin Media, or MCP manageMedia) and ai-image-tagging-enabled is
on, MediaService.saveNewUpload marks it pending and queues it on the media tagging queue. On the
worker, MediaTaggingEventListener sends a resized copy to OpenAiImageAnalysisService, which
asks an OpenAI vision model for 5–15 keywords, a title, alt text, a description and a
focal point (the main person's face, or the main subject; none when the
subject is already in the middle). Keywords are always added; title, alt text, description and
focal point are only filled when blank, so a focal point the merchant set is never replaced. The media screens show
"AI is analysing this image…" and then the result, by polling /admin/rest/media/{id}/ai-status.
This uses the OpenAI key (ai-openai-api-key, falling back to the platform key) and the optional
ai-site-context description of the shop. It does not depend on ai-enabled.
Each media record has a purpose. Product photos (the default, and every record from before the
field existed) are described as products. Photos sent with a change request
have purpose CONTENT, so the prompt asks for the scene, setting, what is happening and how many
people are in it, never who they are, with alt text written for an article.
Design Brief chat¶
Admin → Settings → Design brief (/admin/shopSettings/design-brief) includes a chat with a
"brand strategist" that asks one question at a time about audience, mood, reference brands,
palette and things to avoid. Finalise from chat turns the conversation into the brief's voice,
palette, typography and shape fields; Save compiles them into CSS tokens (see
Site Customization → Design Brief). The model is built per
tenant by TenantAiService from ai-provider / ai-model and requires ai-enabled=true plus an
Anthropic or OpenAI key. Agents read and write the same brief through the MCP getDesignBrief and
manageBranding tools, block colour schemes included; both report which brand colours were given a more readable shade for text (contrast). An agent
can also stage a brief, theme or stylesheet in the shop's private preview and publish it later
(manageBranding previewDesignBrief, publishPreview; see Theme and Style Preview).
AI Menu Generator¶
A panel in the menu editor (/admin/shopSettings/menu). Describe the menu you want; the prompt
includes the shop's collections and pages, and the response becomes the menu tree. The editor posts
the prompt to POST /admin/menu/rest/v2/ai/draft, and MenuAiService runs it through the shop's
own AI set-up (TenantAiService, as for the Design Brief chat), so it needs ai-enabled and a key,
and no API key ever reaches the browser. Prompts are capped in size. Copy Prompt / Paste
Response still lets any external LLM be used instead, including on a shop without AI set up.
Browser-side generators¶
The JSON Component generator, in the jsonComponent extension editor (prompted with
JsonComponentExtension.getAiPrompt()), calls the Anthropic API directly from the admin's browser,
using a Claude API key the admin enters once (kept in the browser's localStorage, never sent to
Badger Commerce). It also offers Copy Prompt / Paste Response.
Configuration¶
Per-site keys (category ai-config, edited at Admin → Settings → Configuration or with MCP
manageSiteConfig):
| Key | Default | Used by |
|---|---|---|
ai-enabled |
false |
Design Brief chat, Menu Generator |
ai-provider |
anthropic |
Design Brief chat, Menu Generator (anthropic or openai) |
ai-model |
claude-sonnet-4-20250514 |
Design Brief chat, Menu Generator (Anthropic) |
ai-openai-model |
gpt-4.1-mini |
Design Brief chat (OpenAI) |
ai-max-tokens |
4096 |
Design Brief chat |
ai-anthropic-api-key |
— (secret) | Design Brief chat, Menu Generator, change requests |
ai-openai-api-key |
— (secret) | Design Brief chat, image tagging, change requests (OpenAI models) |
ai-image-tagging-enabled |
false |
Image tagging |
ai-image-tagging-model |
gpt-5-mini |
Image tagging |
ai-site-context |
— | Image tagging, change requests |
Change requests have their own settings group, change-request-config (Settings → Store → Change
requests): change-requests-enabled, change-request-model, change-request-monthly-limit and
change-request-default-blog. See Switching change requests on.
Global fallbacks for the keys: ai.platform.anthropic.apiKey and ai.platform.openai.apiKey.
Every server-side feature resolves its key the same way: the site's own key for the provider when it
has one, else the platform's.
Not built¶
There is no AI product-description or product-name generation, no AI recommendations, semantic/visual/voice search, customer chatbot, dynamic pricing, fraud detection or forecasting. "Trending products" ranks by page views and "recently viewed" by browsing history; neither uses AI.