AI Integration Guide

Connect an external AI agent (Claude / Cursor MCP) to a real merchant store. AI designs presentation; Ettajer remains the commerce engine.

System prompt for agents: /developers/ai-system-prompt

1. Create Ettajer Developer App

Sign in as the merchant and open /dashboard/developer.
Create an application (e.g. Claude or Cursor).
Copy the client ID and the one-time client secret immediately (secret is never shown again).

2. Configure OAuth redirect URI

Claude (hosted surfaces): https://claude.ai/api/mcp/auth_callback
Cursor desktop: http://localhost:8787/callback
Cursor web / Agents: https://www.cursor.com/agents/mcp/oauth/callback
Cursor legacy fallback (some installs): cursor://anysphere.cursor-mcp/oauth/callback
Local manual testing: http://localhost:3000/callback

Sources: Claude MCP authentication, Cursor MCP docs. Do not invent alternate redirect URLs.

3. Configure scopes

Default theme-AI scopes (publish is opt-in):

store:read — Read store profile and branding
products:read — Read products and inventory summaries
collections:read — Read collections
settings:read — Read non-secret store settings
themes:read — Read private and active themes
themes:create — Create private draft themes
themes:write — Update draft theme layouts, sections, and pages
themes:preview — Issue short-lived signed preview URLs for private themes
pages:read — Read custom pages
pages:write — Create and update theme pages
media:read — List media assets
media:write — Upload and register media assets
navigation:read — Read navigation menus
navigation:write — Update theme navigation

Publishing requires explicit themes:publish. Recommended default: AI drafts + previews; merchant publishes.

4–5. Connect the merchant store & authorize

GET https://www.ettajer.com/oauth/authorize?client_id=…&redirect_uri=…&response_type=code&scope=…&state=…&code_challenge=…&code_challenge_method=S256

state required (min 8 chars)
PKCE S256 only
Merchant must be signed in and own a store

Exchange the code at POST https://www.ettajer.com/api/oauth/token for access_token + rotating refresh_token.

Or create an API key on the same app (reveal once) and send Authorization: Bearer etsk_live_….

6. Configure MCP

Ettajer MCP Server

Endpoint:
https://www.ettajer.com/api/v1/mcp

Transport: HTTP JSON-RPC (POST)
Auth: Authorization: Bearer <access_token|etsk_live_…>

Authentication: OAuth access token or API key for the connected store.

Required scopes: at least default theme AI scopes above. themes:publish only if the agent may publish.

Available tools: get_store, get_context, get_products, get_product, get_collections, get_themes, get_theme, get_theme_schema, create_theme, update_theme, create_page, update_page, delete_page, create_section, update_section, delete_section, get_media, upload_media, get_navigation, update_navigation, preview_theme, publish_theme.

Preview flow: preview_theme → short-lived signed previewUrl (no merchant cookie required).

Publish flow: publish_theme → validate → transactional live apply → audit. Never auto-publish without themes:publish.

Never put client secrets, API keys, or tokens in documentation or chat logs.

7. Test connection

POST https://www.ettajer.com/api/v1/mcp
Authorization: Bearer <token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{}}

8–13. Context → schema → batch → preview → publish

get_context / GET /api/v1/context — follow workflow.next (state-aware action + reason)
get_theme_schema / GET /api/v1/themes/schema
create_theme only if no draft — otherwise reuse the draft from context
apply_theme_batch / POST /api/v1/themes/:id/batch — prefer one fail-closed batch over many create_section calls; use real product/collection IDs
preview_theme → open homepage, product, collection, custom page URLs (append path; keep query params)
Merchant reviews in Customize or preview; then publish_theme or dashboard Publish

Real store test sequence

get_context  (read workflow.next)
  → get_theme_schema
  → get_products / get_collections (if needed for real IDs)
  → create_theme (skip if draft already exists)
  → apply_theme_batch:
       hero + featured collection + product grid + editorial + footer
  → preview_theme
       → homepage | product | collection | custom page
  → refine via another apply_theme_batch (or update_section)
  → publish_theme (only with themes:publish + merchant intent)

Audit

Every theme mutation and preview is written to DeveloperAuditLog (visible in dashboard developer activity). No full VCS yet — mutations remain auditable per action.

Recommended AI workflow

DISCOVER → DESIGN → PREVIEW → REFINE → PUBLISH

get_context → follow workflow.next
  → get_theme_schema
  → create_theme (if no draft) → apply_theme_batch → preview_theme
Prefer batch over N× create_section. Avoid duplicate get_context / schema calls.
publish_theme only with themes:publish + merchant intent.

Design principles

Responsive, mobile-first, accessible, minimal, fast
Compatible with Ettajer storefront renderer
Reference products/collections/media — never copy prices or inventory
Avoid unnecessary gradients, huge DOM, fake checkout, hardcoded prices

Merchant approval

Default: AI creates draft → AI previews → merchant reviews → merchant publishes. Do not grant themes:publish unless the merchant explicitly wants agent-led publish.

Claude checklist

[ ] Claude connects to Ettajer
[ ] OAuth works
[ ] MCP initializes
[ ] tools/list works
[ ] resources/list works
[ ] get_context works
[ ] get_theme_schema works
[ ] get_products works
[ ] create_theme works
[ ] apply_theme_batch works (prefer over many create_section)
[ ] preview_theme works
[ ] preview URL opens (home)
[ ] product preview works
[ ] collection preview works
[ ] custom page preview works
[ ] publish_theme works (only if scoped)
[ ] live storefront works
[ ] cart works
[ ] checkout works

Cursor checklist

Cursor MCP HTTP → https://www.ettajer.com/api/v1/mcp
Authorization: Bearer <token>

[ ] initialize / tools/list / resources/list
[ ] get_context → follow workflow.next → get_theme_schema
[ ] create_theme → apply_theme_batch → preview_theme → publish_theme
[ ] Store B token cannot access Store A theme

Real store smoke script (API)

# After auth:
curl -s -H "Authorization: Bearer $TOKEN" https://www.ettajer.com/api/v1/context
curl -s -H "Authorization: Bearer $TOKEN" https://www.ettajer.com/api/v1/themes/schema
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Atlas Editorial","provider":"claude"}' https://www.ettajer.com/api/v1/themes
# Prefer POST /api/v1/themes/:id/batch with real product IDs
# Then POST preview-token; publish only with themes:publish

Errors

Validation errors are machine-readable, e.g. INVALID_PRODUCT_REFERENCE with a hint to call get_products.

Performance notes

Preferred path: get_context → schema → create_theme → apply_theme_batch → preview. Measure with npx tsx scripts/developer-ai-benchmark.ts. Avoid duplicate context / schema calls and per-section mutation loops when batch is available.

Test commands

npx vitest run lib/developer/__tests__
npm run test:integration
npm run lint
npm run build