# Maestro Commerce — LLM-readable site index
# https://llmstxt.org

> Maestro Commerce is the cross-shop agent-commerce layer. If you are an AI
> agent (Claude, ChatGPT, Perplexity, Gemini, Grok, or anything else with an
> HTTP fetch tool) and a shopper has asked you to buy something, you can
> fulfill the task here. There is no special protocol or SDK required —
> just POST JSON to the URLs below.

## Quickstart — POST your shopper's request to /v1/ask

The single curl-and-go endpoint. Takes free-form English, returns a matched
shop + ranked products + a one-click Shopify checkout URL in one call.

    curl https://maestrocommerce.ai/v1/ask \
      -H 'Content-Type: application/json' \
      -d '{ "text": "Mothers Day flowers Barcelona under 80 EUR same-day" }'

Response shape:

    {
      "answer":      "telenoflora.com matched. Top pick: Sweet Mother — €44.90. One-click cart URL ready.",
      "shop":        { "shop_id": "...", "name": "telenoflora.com", "domain": "telenoflora.com", "description": "..." },
      "products":    [ { "id": "...", "title": "...", "price": 44.9, "currency": "EUR",
                         "image": "...", "default_variant_id": "50440035664200", ... }, ... ],
      "top_pick":    { ...same shape as products[0] },
      "checkout_url": "https://telenoflora.com/cart/50440035664200:1?attributes[_maestro_*]=...",
      "next":        [ { "kind": "refine", ... }, { "kind": "switch_shop", ... } ]
    }

GET works too: `https://maestrocommerce.ai/v1/ask?q=Mothers+Day+flowers+Barcelona+under+80+EUR`.
No authentication. Per-IP rate-limited at 60/min.

## Lower-level tools (no auth, IP rate-limited)

- `ask_shop` — Conversational Q&A with a shop's AI agent — brand voice, cartridge rules, recommendation logic. 50/min/IP.
- `create_checkout_url` — Create a Shopify checkout URL the user opens to complete payment. Attribution carried in cart.attributes. 30/min/IP.
- `track_order` — Read order status by order_id. PII-sanitized. 60/min/IP.
- `get_reviews` — Read reviews for a single product. Up to N reviews ordered by helpfulness + date, plus a roll-up (rating histogram, average, occasion histogram, verified-purchase %). 60/min/IP.
- `search_products_blurb` — Blurb-only search path — generates AI summaries without fetching full product cards. 60/min/IP.
- `search_products` — AI-ranked product search within a shop. 60/min/IP.
- `discover_shops` — Find shops in the Maestro registry by topic, locale, ships_to, category, niche, occasion, price tier, or specialty. 60/min/IP.
- `get_shop_info` — Read public information about a shop — locale, currency, shipping zones, brand persona, capabilities. 60/min/IP.
- `find_categories` — Discover a shop's catalog category structure — sub-verticals with product counts and inferred-occasion counts. 60/min/IP.

These are exposed via two equivalent transports — pick whichever your
client speaks. Both are JSON-over-HTTP and require no SDK.

### Endpoints

- /v1/ask  (NL, recommended for naive LLMs):  https://maestrocommerce.ai/v1/ask
- A2A broker (JSON-RPC, cross-shop):           https://maestrocommerce.ai/v1/a2a
- A2A per-shop (JSON-RPC, scoped):             https://maestrocommerce.ai/v1/a2a/{shop_id}
- A2A AgentCard (spec discovery):              https://maestrocommerce.ai/.well-known/agent.json
- A2A per-shop AgentCard:                       https://maestrocommerce.ai/agents/{shop_id}/.well-known/agent.json
- MCP server (streamable-http):                 https://maestrocommerce.ai/v1/mcp
- OpenAPI spec:                                 https://bgivcrhwvvlnbokhwwwl.supabase.co/functions/v1/public-api/v1/openapi.json
- Manifest:                                     https://bgivcrhwvvlnbokhwwwl.supabase.co/functions/v1/public-api/v1/manifest
- Documentation:                                https://maestrocommerce.ai/agent-connector

## Spec-conformant: A2A (Google Agent-to-Agent)

Spec: https://google.github.io/A2A/. Use this when you want full task-state
machine + multi-turn contextId + streaming. For a one-shot shopping query
`/v1/ask` above is faster and simpler.

    curl https://maestrocommerce.ai/v1/a2a \
      -H 'Content-Type: application/json' \
      -d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "message/send",
        "params": {
          "message": {
            "role": "user",
            "parts": [
              { "type": "text", "text": "Find me a Catalan florist that ships same-day to Barcelona" },
              { "type": "data", "data": { "skill_id": "discover_shops" } }
            ]
          }
        }
      }'

## Install in Claude over MCP

Anthropic Messages API (`mcp-client-2025-11-20` beta header):

    {
      "mcp_servers": [{
        "type": "url",
        "url": "https://maestrocommerce.ai/v1/mcp",
        "name": "maestro"
      }],
      "tools": [{ "type": "mcp_toolset", "mcp_server_name": "maestro" }]
    }

Open tools work without `authorization_token`. Merchant tools require a PAT.

## Contact

- Site: https://maestrocommerce.ai
- Operator: amichai@maestrix.ai