{
  "openrpc": "1.3.2",
  "info": {
    "title": "UCP Common Service",
    "description": "Canonical MCP/JSON-RPC interface for UCP Common services, including Location discovery. 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 Business's discovery profile at `/.well-known/ucp` under `services[\"dev.ucp.common\"][transport=mcp].endpoint`. The server entry below is a placeholder for tooling compatibility.",
    "version": "2026-08-25"
  },
  "servers": [
    {
      "name": "business",
      "url": "{endpoint}",
      "description": "Business-provided endpoint from UCP discovery profile",
      "variables": {
        "endpoint": {
          "default": "https://business.example.com/ucp/mcp",
          "description": "Obtain from /.well-known/ucp → services[\"dev.ucp.common\"][transport=mcp].endpoint"
        }
      }
    }
  ],
  "components": {
    "schemas": {
      "meta": {
        "type": "object",
        "description": "Request metadata mapping to UCP standard headers.",
        "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."
              }
            }
          }
        }
      }
    }
  },
  "methods": [
    {
      "name": "search_locations",
      "summary": "Search for physical locations",
      "description": "Search for physical locations using query text, explicit spatial relations, and structured filters.",
      "params": [
        {
          "name": "meta",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/meta"
          }
        },
        {
          "name": "location",
          "required": true,
          "schema": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_search.json#/$defs/search_request"
          }
        }
      ],
      "result": {
        "name": "response",
        "schema": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_search.json#/$defs/search_response"
        }
      }
    },
    {
      "name": "lookup_locations",
      "summary": "Batch lookup locations by identifier",
      "description": "Batch lookup of physical Locations by supported identifiers, optionally refined by explicit spatial relations and structured filters. Returns matching Locations.",
      "params": [
        {
          "name": "meta",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/meta"
          }
        },
        {
          "name": "location",
          "required": true,
          "schema": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_lookup.json#/$defs/lookup_request"
          }
        }
      ],
      "result": {
        "name": "response",
        "schema": {
          "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_lookup.json#/$defs/lookup_response"
        }
      }
    }
  ]
}