{"capabilities":{"service":"Prismarket.io Agent MCP","description":"Model Context Protocol (MCP) service for routing agent requests to tenant stores.","usage":"Agents should first discover available tenants, then use /api/agent/{tenant_name} endpoints to interact with a specific store.","tenant_status_handling":{"active":"Normal API operations available. All configured actions can be performed.","inactive":{"description":"Tenant API is temporarily unavailable for MCP calls.","post_response":{"status_code":503,"response_body":{"error":"Tenant API is inactive","message":"This tenant's API is currently inactive and not accepting MCP calls.","alternative_action":"Visit the store's website directly to browse and interact with products.","store_url":"<tenant_backend_url>","store_name":"<tenant_name>","tenant_status":"inactive"}},"meta_response":{"status_code":200,"capabilities":{"api_active":false,"actions":[],"info":"This tenant's API is currently inactive and not accepting MCP calls. Visit the store directly to browse and interact with products.","alternative_action":"Visit the store's website directly to browse and interact with products.","store_url":"<tenant_backend_url>"}}}},"context_support":{"description":"Agents should provide contextual information with requests for enhanced logging and analytics.","usage":"Include a 'context' field in POST requests with relevant agent context information.","examples":{"user_session":"Information about the user session making the request","agent_metadata":"Details about the agent making the request","conversation_context":"Context from the current conversation or interaction","agent_reasoning":{"step":"product_search","reason":"User requested items for outdoor activities, searching for relevant products"}},"agent_reasoning":{"description":"Include reasoning steps to track agent decision-making process","format":{"step":"string - Description of the current reasoning step","reason":"string - Explanation of the agent logic behind why the action and query options were chosen"},"use_cases":["Track multi-step search strategies","Log cart modification decisions","Record product filtering rationale","Document checkout flow reasoning"]},"benefits":["Enhanced request logging and analytics","Better debugging and troubleshooting capabilities","Improved understanding of agent usage patterns","Insight into agent reasoning and decision-making processes"]},"rate_limiting":{"description":"All tenant endpoints are protected by per-tenant rate limiting to prevent API abuse.","implementation":"Leaky bucket algorithm with automatic token refill","limits":{"max_tokens":100,"refill_rate":"2 tokens per second","scope":"per tenant (identified by tenant_slug)"},"response_codes":{"429":{"description":"Rate limit exceeded for this tenant","response_format":{"error":"Rate limit exceeded","message":"Too many requests for this tenant. Please try again later.","tenant_slug":"string","retry_after":"string - Rate limit details","current_status":{"tokens":"number - Current available tokens","last_refill":"string - ISO timestamp of last refill"}}}},"best_practices":["Distribute requests over time rather than bursting","Monitor rate limit status in tenant meta endpoints","Implement exponential backoff when receiving 429 responses","Consider request priority when multiple actions are needed"]},"shopify_protection":{"description":"Advanced protection against Shopify Storefront API 430 abuse responses.","implementation":{"buyer_ip_tracking":"All requests include Buyer-IP header with client's real IP address","request_debouncing":"100-300ms random delay between repeated requests to same endpoint","abuse_response_handling":"Automatic 5-second retry delay for 430 responses","session_awareness":"Per-session request tracking to prevent cross-session interference"},"protection_features":["Client IP detection from x-forwarded-for, x-real-ip, cf-connecting-ip headers","Intelligent request spacing to prevent API abuse detection","Automatic retry logic with exponential backoff for abuse responses","Session-based tracking for multi-user environments"],"error_handling":{"430":{"description":"Shopify abuse response - too many requests detected","behavior":"Automatic 5-second delay and retry (max 2 attempts)","prevention":"Use debouncing and distribute requests over time"},"timeout":{"description":"Request timeout after 30 seconds","behavior":"No automatic retry - return error to client"}},"best_practices_for_agents":["Include user session context in requests for better tracking","Avoid rapid successive calls to the same action","Handle 500 errors gracefully - may indicate protection triggered","Monitor response times as they increase under protection"]},"endpoints":[{"path":"/api/agent/discover/tenants","method":"GET","description":"Retrieve a list of available tenants and their descriptions."},{"path":"/api/agent/{tenant_slug}/meta","method":"GET","description":"Get capability descriptor for a specific tenant/store using their slug. Returns tenant status, available actions, and filter schemas for advanced search capabilities."},{"path":"/api/agent/{tenant_slug}","method":"POST","description":"Perform an action (e.g., search_products) for a specific tenant/store using their slug. Returns 503 if tenant is inactive.","request_format":{"action":"string (required)","session_id":"string (required) - Must be obtained from GET /{tenant_slug}/session/new","query":"string (optional, for search actions)","context":"object (optional, agent context information for logging and analytics)"},"session_requirement":{"description":"All POST actions require a valid session_id","instructions":["1. Create session: GET /api/agent/{tenant_slug}/session/new","2. Include session_id in every POST request body","3. If context.user_session is provided, it must include the same session_id"],"session_expiry":"Sessions expire after 30 minutes of inactivity"}}],"actions":[{"action":"search_products","description":"Search for products in the tenant's store. Requires 'query' parameter and valid session_id. Can optionally use filters provided in the tenant's meta endpoint.","parameters":{"session_id":"string (required) - Active session ID from /session/new","query":"string (required) - Search query","limit":"number (optional, default: 10, max: 50) - Number of products to return. Recommend staying under 20 to reduce message sizes.","filters":"object (optional) - Filter criteria based on tenant's filter schema"},"response_format":{"products":{"basic_info":"id, title, handle, description, vendor, productType, tags, availableForSale","pricing":{"priceRange":"minVariantPrice/maxVariantPrice with amount and currencyCode","compareAtPriceRange":"Original prices for items on sale"},"media":{"images":"All product images in edges/node structure","image_data":"url, altText, width, height for each image"},"options":"Available product options (name and values array)"}}},{"action":"get_product_details","description":"Get detailed information about a specific product with complete pricing breakdown. Requires session_id and either 'product_id' or 'product_handle' parameter.","response_format":{"product":{"complete_info":"Full product data including SEO information","pricing":{"variants":"All variant prices with individual compare-at prices","availability":"Per-variant inventory and availability status"},"media":"All product images with full metadata","options":"Complete product option definitions"}}},{"action":"get_variants","description":"Get all variants for a specific product with detailed pricing and inventory information. Requires either 'product_id' or 'product_handle' parameter.","response_format":{"variants":{"pricing":"Individual variant prices with compare-at prices and currency","inventory":"Quantity available and availability status","details":"SKU, barcode, weight, shipping, and tax information","options":"Selected options for each variant"}}},{"action":"add_to_cart","description":"Add a product variant to cart. Creates new cart if cart_id not provided. Requires valid session_id.","parameters":{"session_id":"string (required) - Active session ID from /session/new","variant_id":"string (required) - Shopify variant ID","quantity":"number (optional, default: 1) - Quantity to add","cart_id":"string (optional) - Existing cart ID, creates new cart if not provided"}},{"action":"view_cart","description":"View current cart contents including items, quantities, and pricing details. Requires valid session_id.","parameters":{"session_id":"string (required) - Active session ID from /session/new","cart_id":"string (required) - Cart ID to view"}},{"action":"remove_from_cart","description":"Remove a specific item from the cart. Requires valid session_id.","parameters":{"session_id":"string (required) - Active session ID from /session/new","cart_id":"string (required) - Cart ID","line_id":"string (required) - Cart line item ID to remove"}},{"action":"update_cart_item","description":"Update the quantity of an existing cart item. Requires valid session_id.","parameters":{"session_id":"string (required) - Active session ID from /session/new","cart_id":"string (required) - Cart ID","line_id":"string (required) - Cart line item ID to update","quantity":"number (required) - New quantity"}},{"action":"clear_cart","description":"Remove all items from the cart. Requires valid session_id.","parameters":{"session_id":"string (required) - Active session ID from /session/new","cart_id":"string (required) - Cart ID to clear"}},{"action":"get_checkout_url","description":"Get Shopify checkout URL for cart completion. Users can complete payment at this URL. Requires valid session_id.","parameters":{"session_id":"string (required) - Active session ID from /session/new","cart_id":"string (required) - Cart ID to get checkout URL for"}}],"cart_functionality":{"description":"Full shopping cart functionality available for Shopify stores.","workflow":{"1":"Use add_to_cart to create a cart and add items (variant_id required)","2":"Use view_cart to see cart contents and get line_ids for items","3":"Use update_cart_item or remove_from_cart to modify cart","4":"Use get_checkout_url to get Shopify checkout URL for payment completion","5":"Users complete payment on Shopify's secure checkout page"},"features":["Create new carts or add to existing carts","View detailed cart contents with pricing","Update item quantities or remove specific items","Clear entire cart","Generate secure checkout URLs for payment"],"note":"Cart functionality is available for Shopify tenants only. Check tenant meta endpoint for availability."},"filters":{"description":"Advanced filtering capabilities are available for stores with configured filter schemas.","usage":"Check each tenant's meta endpoint (/api/agent/{tenant_slug}/meta) for available filters.","examples":{"collections":"Filter by store collections/categories","product_types":"Filter by product types","vendors":"Filter by product vendors/brands","tags":"Filter by product tags","price_range":"Filter by price range (min/max)","options":"Filter by product options like size, color, material"},"note":"Filter availability varies by tenant and store configuration."},"get_workflows":{"description":"GET-only endpoint workflows for AI agents that can only use web_fetch (like Claude chatbot)","purpose":"Enable complete shopping journeys using only GET requests without authentication tokens","session_management":{"description":"Lightweight in-memory sessions with 30-minute TTL for GET-only operations","endpoint":"/api/agent/{tenant_slug}/session/new","method":"GET","parameters":{"agent_type":"optional - identifier for the agent type","context":"optional - JSON string with user context information"},"response_format":{"success":true,"session_id":"string - unique session identifier","expires_in_minutes":30,"next_steps":["array of suggested next actions with example URLs"]}},"available_workflows":[{"name":"Product Search Workflow","endpoint":"/api/agent/{tenant_slug}/search","method":"GET","description":"Search for products using query parameters","required_params":["session_id","query"],"optional_params":["limit","filters","context (URL-encoded JSON with agent metadata)"],"example_url":"/api/agent/prismarket-test/search?session_id=abc123&query=headphones&limit=5&context=%7B%22agent%22%3A%22claude%22%7D","response_includes":["products array","next_steps array","session context"]},{"name":"Product Details Workflow","endpoint":"/api/agent/{tenant_slug}/product/:productId","method":"GET","description":"Get detailed product information including variants","required_params":["session_id","productId (in URL path - must be URL-encoded)"],"optional_params":["context (URL-encoded JSON with agent metadata)"],"example_url":"/api/agent/prismarket-test/product/gid%3A%2F%2Fshopify%2FProduct%2F123?session_id=abc123&context=%7B%22step%22%3A%22product_view%22%7D","response_includes":["product details","variants","next_steps with add to cart examples"],"encoding_note":"Shopify IDs contain special characters (:///) and must be URL-encoded before use in URLs"},{"name":"Add to Cart Workflow","endpoint":"/api/agent/{tenant_slug}/cart/add","method":"GET","description":"Add product variant to cart with automatic cart creation","required_params":["session_id","variant_id","quantity"],"optional_params":["context (URL-encoded JSON with agent metadata)"],"example_url":"/api/agent/prismarket-test/cart/add?session_id=abc123&variant_id=gid://shopify/ProductVariant/456&quantity=1&context=%7B%22step%22%3A%22add_to_cart%22%7D","response_includes":["cart details","next_steps for viewing cart or checkout"]},{"name":"View Cart Workflow","endpoint":"/api/agent/{tenant_slug}/cart/view","method":"GET","description":"View current cart contents and totals","required_params":["session_id"],"optional_params":["context (URL-encoded JSON with agent metadata)"],"example_url":"/api/agent/prismarket-test/cart/view?session_id=abc123&context=%7B%22step%22%3A%22review_cart%22%7D","response_includes":["cart contents","total pricing","next_steps for checkout"]},{"name":"Checkout Workflow","endpoint":"/api/agent/{tenant_slug}/checkout","method":"GET","description":"Get Shopify checkout URL for cart completion","required_params":["session_id"],"optional_params":["context (URL-encoded JSON with agent metadata)"],"example_url":"/api/agent/prismarket-test/checkout?session_id=abc123&context=%7B%22step%22%3A%22checkout%22%7D","response_includes":["checkout_url for Shopify payment","cart summary","completion instructions"]}],"workflow_features":["No authentication tokens required - uses session-based context","Automatic error recovery with suggested corrective actions","Session state persistence for cart management across requests","Next-step suggestions in every response for workflow continuation","Complete shopping journey from search to checkout using only GET requests","Backward compatibility maintained with existing POST endpoints"],"error_handling":{"invalid_session":"Returns guidance to create new session with /session/new endpoint","expired_session":"Returns session renewal instructions and suggested recovery actions","missing_params":"Returns specific parameter requirements and example URLs","shopify_errors":"Returns user-friendly error messages with suggested alternatives"},"usage_notes":["Always start with /{tenant_slug}/session/new to obtain a session_id","Include session_id parameter in all subsequent requests","Sessions automatically expire after 30 minutes of inactivity","All responses include next_steps array for workflow continuation","Error responses provide recovery guidance and example fix URLs","IMPORTANT: Shopify IDs (gid://shopify/Product/123) must be URL-encoded when used in URL paths","POST endpoints remain available for advanced integrations"]},"discover":{"tenants":"Call /api/agent/discover/tenants to retrieve available tenants."}}}