A read-only JSON API and an MCP server. Search the index, pick a variant, open its cart_url on the merchant's store and complete checkout there. No API key needed in the MVP.
| 1 | GET /api/search?q=trail+shoes&max_price=150&in_stock=1 |
|---|---|
| 2 | GET /api/product/{id} to see every variant, its price and availability |
| 3 | Open the variant's cart_url (https://store/cart/VARIANT_ID:1). It loads the merchant's checkout with that item in it. |
| Endpoint | Params | Returns |
|---|---|---|
GET /api/search | q, max_price, min_price, in_stock (1), store, limit (≤100), offset | {total, results[]} |
GET /api/product/:id | product with variants[] | |
GET /api/stores | indexed merchants, counts, last crawl | |
POST /mcp | JSON-RPC 2.0 | MCP over HTTP |
/openapi.json · /llms.txt · /.well-known/mcp.json | discovery |
{
"id": "allbirds-6993167188048",
"title": "Men's Tree Runner",
"store": "allbirds.com",
"price": 98.0, "currency": "USD", "in_stock": true,
"url": "https://www.allbirds.com/products/mens-tree-runners",
"cart_url": "https://www.allbirds.com/cart/40404858831056:1",
"checkout": "merchant"
}
Tools: search_products(q, max_price?, min_price?, in_stock?, store?, limit?) and get_product(id).
# stdio (Claude Desktop, Cursor, etc.)
{ "mcpServers": { "botshop": { "command": "python3", "args": ["/path/to/botshop/mcp_stdio.py"] } } }
# HTTP
curl -s localhost:9393/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"q":"coffee","max_price":20}}}'
Prices and stock are refreshed from each merchant's public catalog and can be stale; the merchant's checkout is the source of truth. BotShop never sees payment details.