portage-ucp 0.1.0

data/schemas/2026-04-08/services/shopping/mcp.openrpc.json

@@ -0,0 +1,492 @@
+{
+  "openrpc": "1.3.2",
+  "info": {
+    "title": "UCP Shopping Service",
+    "description": "Canonical MCP/JSON-RPC interface for UCP Shopping service. Schema references are logical pointers - actual payload shape is determined by negotiated capabilities.\n\n**Endpoint Resolution:** This spec defines methods only. The endpoint URL MUST be obtained from the merchant's discovery profile at `/.well-known/ucp` under `services[\"dev.ucp.shopping\"][transport=mcp].endpoint`. The server entry below is a placeholder for tooling compatibility.",
+    "version": "2026-04-08"
+  },
+  "servers": [
+    {
+      "name": "merchant",
+      "url": "{endpoint}",
+      "description": "Merchant-provided endpoint from UCP discovery profile",
+      "variables": {
+        "endpoint": {
+          "default": "https://merchant.example.com/ucp/mcp",
+          "description": "Obtain from /.well-known/ucp → services[\"dev.ucp.shopping\"][transport=mcp].endpoint"
+        }
+      }
+    }
+  ],
+  "components": {
+    "schemas": {
+      "checkout_result": {
+        "oneOf": [
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+          },
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+          }
+        ]
+      },
+      "cart_result": {
+        "oneOf": [
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json"
+          },
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+          }
+        ]
+      },
+      "order_result": {
+        "oneOf": [
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/order.json"
+          },
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+          }
+        ]
+      },
+      "catalog_get_product_result": {
+        "oneOf": [
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json#/$defs/get_product_response"
+          },
+          {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json"
+          }
+        ]
+      },
+      "meta": {
+        "type": "object",
+        "description": "Request metadata.",
+        "required": [
+          "ucp-agent"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "ucp-agent": {
+            "type": "object",
+            "description": "Platform agent identification. Maps to HTTP UCP-Agent header.",
+            "required": [
+              "profile"
+            ],
+            "properties": {
+              "profile": {
+                "type": "string",
+                "format": "uri",
+                "description": "URL to the platform's UCP profile document."
+              }
+            }
+          },
+          "idempotency-key": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique key for retry safety. Maps to HTTP Idempotency-Key header."
+          }
+        }
+      }
+    }
+  },
+  "methods": [
+    {
+      "name": "create_checkout",
+      "summary": "Create a checkout",
+      "description": "Create a new checkout session.",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+          }
+        }
+      ],
+      "result": {
+        "name": "checkout",
+        "schema": {
+          "$ref": "#/components/schemas/checkout_result"
+        }
+      }
+    },
+    {
+      "name": "get_checkout",
+      "summary": "Get checkout",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "checkout",
+        "schema": {
+          "$ref": "#/components/schemas/checkout_result"
+        }
+      }
+    },
+    {
+      "name": "update_checkout",
+      "summary": "Update checkout",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+          }
+        }
+      ],
+      "result": {
+        "name": "checkout",
+        "schema": {
+          "$ref": "#/components/schemas/checkout_result"
+        }
+      }
+    },
+    {
+      "name": "complete_checkout",
+      "summary": "Complete checkout and place order",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/meta"
+              },
+              {
+                "required": [
+                  "ucp-agent",
+                  "idempotency-key"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "checkout",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+          }
+        }
+      ],
+      "result": {
+        "name": "checkout",
+        "schema": {
+          "$ref": "#/components/schemas/checkout_result"
+        }
+      }
+    },
+    {
+      "name": "cancel_checkout",
+      "summary": "Cancel checkout",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/meta"
+              },
+              {
+                "required": [
+                  "ucp-agent",
+                  "idempotency-key"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "checkout",
+        "schema": {
+          "$ref": "#/components/schemas/checkout_result"
+        }
+      }
+    },
+    {
+      "name": "create_cart",
+      "summary": "Create a cart",
+      "description": "Create a new cart session.",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json"
+          }
+        }
+      ],
+      "result": {
+        "name": "cart",
+        "schema": {
+          "$ref": "#/components/schemas/cart_result"
+        }
+      }
+    },
+    {
+      "name": "get_cart",
+      "summary": "Get cart",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "cart",
+        "schema": {
+          "$ref": "#/components/schemas/cart_result"
+        }
+      }
+    },
+    {
+      "name": "update_cart",
+      "summary": "Update cart",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "cart",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json"
+          }
+        }
+      ],
+      "result": {
+        "name": "cart",
+        "schema": {
+          "$ref": "#/components/schemas/cart_result"
+        }
+      }
+    },
+    {
+      "name": "cancel_cart",
+      "summary": "Cancel cart",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/meta"
+              },
+              {
+                "required": [
+                  "ucp-agent",
+                  "idempotency-key"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "cart",
+        "schema": {
+          "$ref": "#/components/schemas/cart_result"
+        }
+      }
+    },
+    {
+      "name": "search_catalog",
+      "summary": "Search for products in the catalog",
+      "description": "Search for products using query text, filters, and pagination.",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "catalog",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json#/$defs/search_request"
+          }
+        }
+      ],
+      "result": {
+        "name": "response",
+        "schema": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json#/$defs/search_response"
+        }
+      }
+    },
+    {
+      "name": "lookup_catalog",
+      "summary": "Batch lookup products or variants by identifier",
+      "description": "Batch lookup of products or variants by identifier. See Catalog Lookup capability for supported identifier types and resolution behavior.",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "catalog",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json#/$defs/lookup_request"
+          }
+        }
+      ],
+      "result": {
+        "name": "response",
+        "schema": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json#/$defs/lookup_response"
+        }
+      }
+    },
+    {
+      "name": "get_order",
+      "summary": "Get order",
+      "description": "Get the current state of an order. Returns the full order entity as a current-state snapshot.",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "description": "The unique identifier of the order."
+          }
+        }
+      ],
+      "result": {
+        "name": "order",
+        "schema": {
+          "$ref": "#/components/schemas/order_result"
+        }
+      }
+    },
+    {
+      "name": "get_product",
+      "summary": "Get product details",
+      "description": "Retrieve complete product detail by identifier with optional interactive option selection.",
+      "params": [
+        {
+          "name": "meta",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/meta"
+          }
+        },
+        {
+          "name": "catalog",
+          "required": true,
+          "schema": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json#/$defs/get_product_request"
+          }
+        }
+      ],
+      "result": {
+        "name": "response",
+        "schema": {
+          "$ref": "#/components/schemas/catalog_get_product_result"
+        }
+      }
+    }
+  ]
+}