{"openapi":"3.1.0","info":{"title":"OpenShopGraph MCP Server","version":"0.1.0","description":"Tools exposed over REST (/tool/*) and the MCP protocol (/mcp, stdio)."},"servers":[{"url":"http://localhost:4010","description":"OpenShopGraph API"}],"components":{"securitySchemes":{"ApiToken":{"type":"apiKey","in":"header","name":"x-api-token"},"OpsKey":{"type":"apiKey","in":"header","name":"x-ops-key"}}},"paths":{"/tool/find_product":{"post":{"operationId":"find_product","summary":"Search the canonical product catalog by free-text query. Returns matching products (id, name, gtin).","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/get_product":{"post":{"operationId":"get_product","summary":"Fetch a single canonical product by id.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/find_offers":{"post":{"operationId":"find_offers","summary":"List merchant offers, optionally filtered by product_id and/or shop_domain.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"shop_domain":{"type":"string"}},"required":[]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/list_coupons":{"post":{"operationId":"list_coupons","summary":"List coupons, optionally filtered by shop_domain.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_domain":{"type":"string"}},"required":[]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/get_trust":{"post":{"operationId":"get_trust","summary":"Get the aggregated trust signal for a shop (by id or domain).","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_id_or_domain":{"type":"string"}},"required":["shop_id_or_domain"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/list_shipping_options":{"post":{"operationId":"list_shipping_options","summary":"List shipping options for a shop (by id or domain).","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_id_or_domain":{"type":"string"},"country":{"type":"string"}},"required":["shop_id_or_domain"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/compare_offers":{"post":{"operationId":"compare_offers","summary":"Compare specific offers by id, sorted by price.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_ids":{"type":"array","items":{"type":"string"}}},"required":["offer_ids"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/compare_prices":{"post":{"operationId":"compare_prices","summary":"The price-comparison query: all merchants for a product ranked by total cost (price + shipping − best coupon), with delivery time and merchant rating.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"new_customer":{"type":"boolean"}},"required":["product_id"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/price_analytics":{"post":{"operationId":"price_analytics","summary":"Price-drop detection + lowest-price tracking for an offer, derived from its price time-series.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string"}},"required":["offer_id"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/find_shop":{"post":{"operationId":"find_shop","summary":"Search shops by free-text query, optionally filtered by country. Returns the public shop view.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"country":{"type":"string"}},"required":["query"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/get_shop":{"post":{"operationId":"get_shop","summary":"Fetch a shop (by id or domain) with its offers (public view).","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_id_or_domain":{"type":"string"}},"required":["shop_id_or_domain"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/report_code":{"post":{"operationId":"report_code","summary":"Report that a shop/code pair is invalid, expired, store-specific, or worked. PII-free customer signal.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_domain":{"type":"string"},"code":{"type":"string"},"reason":{},"note":{"type":"string"}},"required":["shop_domain","code","reason"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/monetize_offer":{"post":{"operationId":"monetize_offer","summary":"Monetized checkout URL + monetization metadata for an offer.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string"},"affiliate":{"type":"boolean"}},"required":["offer_id"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/resolve_checkout_url":{"post":{"operationId":"resolve_checkout_url","summary":"Validated checkout URL for an offer.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string"},"affiliate":{"type":"boolean"}},"required":["offer_id"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/resolve_conflict":{"post":{"operationId":"resolve_conflict","summary":"Audit a shop-merge intent (read-only on the seed backend).","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from_shop_id":{"type":"string"},"to_shop_id":{"type":"string"}},"required":["from_shop_id"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/internal_trust":{"post":{"operationId":"internal_trust","summary":"Internal trust signals from click⨝transaction event data.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_id_or_domain":{"type":"string"}},"required":["shop_id_or_domain"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/trust_adapter":{"post":{"operationId":"trust_adapter","summary":"External trust-provider adapter payload.","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"domain":{"type":"string"}},"required":["provider","domain"]}}}},"responses":{"200":{"description":"OK"},"400":{"description":"invalid input"},"404":{"description":"not found"}}}},"/tool/audit_log":{"get":{"operationId":"audit_log","summary":"In-memory audit log of conflict-resolution actions.","security":[{"ApiToken":[]}],"responses":{"200":{"description":"OK"}}}},"/mcp":{"post":{"operationId":"mcp_jsonrpc","summary":"MCP protocol over streamable-HTTP (JSON-RPC: initialize, tools/list, tools/call). Same tools as /tool/*.","responses":{"200":{"description":"JSON-RPC response or SSE stream"}}}},"/suggest":{"get":{"operationId":"suggest","summary":"Public typeahead: category + shop suggestions for a query prefix (trgm fuzzy + popularity). No auth.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"query prefix"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":8}},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 filter"}],"responses":{"200":{"description":"OK"}}}},"/health":{"get":{"operationId":"health","summary":"Liveness probe.","responses":{"200":{"description":"ok"}}}},"/ready":{"get":{"operationId":"ready","summary":"Readiness probe.","responses":{"200":{"description":"ready"}}}},"/api/ops/state":{"get":{"operationId":"ops_state","summary":"Machine-readable ops state (shop counts/freshness, catalog sizes, flags, consumers, resource accounts). Optional x-ops-key guard (OPS_API_KEY).","security":[{"OpsKey":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"missing/invalid x-ops-key (only when OPS_API_KEY is set)"}}}},"/metrics/resources":{"get":{"operationId":"metrics_resources","summary":"Resource accounts (DataForSEO/MiniMax/LiteLLM) in Prometheus text format.","responses":{"200":{"description":"Prometheus exposition"}}}}}}