Subchapter 1.1

Agent Friendly

reference/agent-friendly.mdMarkdown24 KBView on GitHub

Agent-Friendly Storefronts

Agent Friendly · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs

Category	Weight	Items (H = high, M = medium, L = low)
Access	25%	H: agent UAs not blocked · H: robots.txt allows AI search + user agents · H: no CAPTCHA on home/PDP/cart · M: no age/consent/geo gate hiding content
Product data	25%	H: name/price/availability in server HTML · H: complete Product JSON-LD matching visible price · M: variants as `ProductGroup` · M: return + shipping structured data · L: OpenGraph product tags
Operability	20%	H: add-to-cart is a named `<button>` in a `<form>` · H: variant selectors are real controls · H: accessible names/labels · H: GET search URL · M: policy pages linked sitewide · L: landmarks, one `h1`, `lang`, alt
Discovery	15%	H: sitemap in robots.txt with live product URLs · M: canonical + real 404s · M: fast TTFB, light HTML · L: Markdown alternative · L: `/llms.txt`
Agentic commerce	15%	H: UCP profile · H: live agent endpoint · M: cart/checkout permalinks · M: OAuth discovery · L (bonus): WebMCP, A2A card, ai-catalog, api-catalog, `rel="ucp"`

// Next.js App Router: app/robots.ts
import type { MetadataRoute } from "next"

export default function robots(): MetadataRoute.Robots {
  const base = process.env.NEXT_PUBLIC_BASE_URL
  return {
    rules: [
      { userAgent: "*", allow: "/", disallow: ["/cart", "/checkout", "/account"] },
      // Optional: opt out of AI training only
      { userAgent: ["GPTBot", "ClaudeBot", "Google-Extended"], disallow: "/" },
    ],
    sitemap: `${base}/sitemap.xml`,
  }
}

{
  "@context": "https://schema.org",
  "@type": "ProductGroup",
  "name": "Classic Tee",
  "description": "Heavyweight cotton t-shirt",
  "image": "https://example.com/tee.jpg",
  "brand": { "@type": "Brand", "name": "Acme" },
  "productGroupID": "prod_123",
  "variesBy": ["https://schema.org/size", "https://schema.org/color"],
  "hasVariant": [
    {
      "@type": "Product",
      "name": "Classic Tee - M / Navy",
      "sku": "TEE-M-NAVY",
      "size": "M",
      "color": "Navy",
      "image": "https://example.com/tee-navy.jpg",
      "offers": {
        "@type": "Offer",
        "url": "https://example.com/products/classic-tee?variant=variant_456",
        "sku": "TEE-M-NAVY",
        "price": "29.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock",
        "itemCondition": "https://schema.org/NewCondition"
      }
    }
  ]
}

// Form posts to a real route; JS can intercept onSubmit for the cart popup
<form method="post" action="/cart/add" onSubmit={handleAddToCart}>
  <input type="hidden" name="variant_id" value={selectedVariant.id} />
  <input type="hidden" name="quantity" value="1" />
  {/* variant selectors go inside this form */}
  <button type="submit" disabled={!inStock}>
    {inStock ? "Add to cart" : "Sold out"}
  </button>
</form>

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": { "@type": "EntryPoint", "urlTemplate": "https://example.com/search?q={search_term_string}" },
    "query-input": "required name=search_term_string"
  }
}

# Acme Store

> Sustainable basics. Ships to US, CA and EU. Prices in USD/EUR.

## Shop
- [All products](https://example.com/store)
- [T-shirts](https://example.com/categories/t-shirts)
- Search: https://example.com/search?q={query}

## Policies
- [Shipping](https://example.com/shipping)
- [Returns](https://example.com/returns)
- [Contact](https://example.com/contact)

## For agents
- [Sitemap](https://example.com/sitemap.xml)

Medusa MCP (Cloud): Medusa Cloud projects on any plan get the Medusa MCP (opens in a new tab) at https://cloud.medusajs.com/mcp. It’s a read-only, merchant-facing server: the merchant signs in with their Cloud account (OAuth) so AI tools can query their orders, products, customers and Store/Admin API data, as well as Cloud data such as deployments, logs, and environment variables. It doesn’t count as the shopper-facing agent endpoint in section 5: it can’t create carts or check out, it only accepts the merchant’s own Cloud login, and it isn’t declared in a store’s /.well-known/ucp. Suggest it when the merchant wants to manage or analyze their store with AI, not for making the storefront shoppable by agents.
Not built in: Medusa has no built-in UCP, shopper-facing MCP or llms.txt for storefronts. They’re buildable with custom API routes/storefront routes. A third-party UCP/ACP plugin exists in the Medusa integrations directory. Medusa has an official Agentic Commerce (OpenAI ACP) tutorial (opens in a new tab).
Known gaps in Medusa’s Next.js starter (check the user’s copy - it may have been changed):
- No Product JSON-LD, sitemap.xml, robots.txt or llms.txt → add app/sitemap.ts, app/robots.ts, app/llms.txt/route.ts and JSON-LD in the product page server component.
- Add-to-cart <button> isn’t inside a <form> → wrap it in a <form method="post" action="..."> posting to a real route.
- Middleware redirects / → /{countryCode} → consider serving a default region at /.
- No search page → add a /[countryCode]/search route that queries the Store API products endpoint with q and server-renders results.
JSON-LD / OG prices: use variant.calculated_price.calculated_amount as-is (don’t divide by 100) with the region’s currency. Fetch products with region_id or prices will be missing.
Availability: derive from the variant’s inventory fields (manage_inventory, allow_backorder, inventory_quantity). Verify the exact fields and fields query param via the Medusa MCP/docs before writing code.
Unknown handle: call notFound() when the Store API returns no product.
Cart permalinks: implement as a storefront route that creates a cart, adds line items through the Store API, then redirects to checkout. Verify the SDK methods first (see the verification workflow in SKILL.md).

# Product facts + JSON-LD + ATC form in raw HTML (no JS)
curl -s https://example.com/products/classic-tee | grep -iE 'application/ld\+json|<form|type="submit"|in stock|\$[0-9]'

# Agent UA gets the same page
curl -s -o /dev/null -w "%{http_code}\n" -A "ChatGPT-User/1.0" https://example.com/products/classic-tee

# robots.txt (200, text/plain, Sitemap line) and sitemap
curl -si https://example.com/robots.txt
curl -s https://example.com/sitemap.xml | head

# Real 404 for unknown products (expect 404)
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/products/does-not-exist-123

# GET search returns product links
curl -s "https://example.com/search?q=tee" | grep -o 'href="[^"]*/products/[^"]*"' | head

# TTFB < 0.8s and HTML size < 1 MB
curl -s -o /dev/null -w "%{time_starttransfer}s %{size_download} bytes\n" https://example.com/products/classic-tee

# Optional: Markdown, llms.txt, UCP
curl -sI -H "Accept: text/markdown" https://example.com/products/classic-tee | grep -i content-type
curl -si https://example.com/llms.txt | head
curl -s https://example.com/.well-known/ucp