{
  "name": "mlsgrid-php-api",
  "title": "MLS Grid Local PHP API",
  "description": "MCP-style descriptor for the local PHP API that serves cached MLS Grid data from the MLS Grid PHP/XAMPP application.",
  "version": "1.0.0",
  "baseUrl": "http://localhost/mlsgrid/public",
  "productionBaseUrl": "https://your-domain.example/mlsgrid/public",
  "authentication": {
    "type": "apiKey",
    "acceptedHeaders": [
      {
        "name": "Authorization",
        "format": "Bearer ${MLSGRID_LOCAL_API_KEY}"
      },
      {
        "name": "X-API-Key",
        "format": "${MLSGRID_LOCAL_API_KEY}"
      }
    ],
    "notes": [
      "Use a local customer or agent API key issued from the admin area.",
      "Do not use or expose the upstream MLS Grid OAuth2 access token."
    ]
  },
  "resources": [
    "Property",
    "Member",
    "Office",
    "OpenHouse",
    "Lookup"
  ],
  "tools": [
    {
      "name": "mlsgrid_search_properties",
      "description": "Search cached property listings through the local MLS Grid-compatible Property endpoint.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "originatingSystemName"
        ],
        "properties": {
          "originatingSystemName": {
            "type": "string",
            "description": "Required MLS origin system, for example mfrmls."
          },
          "listingId": {
            "type": "string",
            "description": "Optional ListingId to fetch one listing."
          },
          "standardStatuses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional StandardStatus values, for example Active, ActiveUnderContract, ComingSoon, Pending."
          },
          "mlgCanView": {
            "type": "boolean",
            "description": "Optional visibility filter."
          },
          "expandMedia": {
            "type": "boolean",
            "default": true,
            "description": "When true, request expanded Media data where available."
          },
          "top": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 100
          },
          "skip": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        }
      },
      "http": {
        "method": "GET",
        "path": "/v2/Property",
        "query": {
          "$filter": "OriginatingSystemName eq '{originatingSystemName}' and optional ListingId/StandardStatus/MlgCanView filters",
          "$expand": "Media when expandMedia is true",
          "$top": "{top}",
          "$skip": "{skip}"
        }
      },
      "example": {
        "url": "http://localhost/mlsgrid/public/v2/Property?$filter=OriginatingSystemName%20eq%20'mfrmls'%20and%20MlgCanView%20eq%20true%20and%20StandardStatus%20in%20('Active','ActiveUnderContract','ComingSoon','Pending')&$expand=Media&$top=100&$skip=0"
      }
    },
    {
      "name": "mlsgrid_get_property_by_listing_id",
      "description": "Fetch one cached property listing by ListingId.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "originatingSystemName",
          "listingId"
        ],
        "properties": {
          "originatingSystemName": {
            "type": "string"
          },
          "listingId": {
            "type": "string"
          },
          "expandMedia": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "http": {
        "method": "GET",
        "path": "/v2/Property",
        "query": {
          "$filter": "OriginatingSystemName eq '{originatingSystemName}' and ListingId eq '{listingId}'",
          "$expand": "Media when expandMedia is true",
          "$top": "1"
        }
      },
      "example": {
        "url": "http://localhost/mlsgrid/public/v2/Property?$filter=OriginatingSystemName%20eq%20'mfrmls'%20and%20ListingId%20eq%20'MFRW7872362'&$expand=Media&$top=1"
      }
    },
    {
      "name": "mlsgrid_search_resource",
      "description": "Search any supported cached MLS resource through the local MLS Grid-compatible v2 endpoint.",
      "inputSchema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource",
          "originatingSystemName"
        ],
        "properties": {
          "resource": {
            "type": "string",
            "enum": [
              "Property",
              "Member",
              "Office",
              "OpenHouse",
              "Lookup"
            ]
          },
          "originatingSystemName": {
            "type": "string"
          },
          "filter": {
            "type": "string",
            "description": "Additional OData-like filter clauses to append after the required OriginatingSystemName clause."
          },
          "expand": {
            "type": "string",
            "description": "Optional expand value, such as Media."
          },
          "top": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 100
          },
          "skip": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        }
      },
      "http": {
        "method": "GET",
        "path": "/v2/{resource}",
        "query": {
          "$filter": "OriginatingSystemName eq '{originatingSystemName}' and optional filter",
          "$expand": "{expand}",
          "$top": "{top}",
          "$skip": "{skip}"
        }
      },
      "example": {
        "url": "http://localhost/mlsgrid/public/v2/OpenHouse?$filter=OriginatingSystemName%20eq%20'mfrmls'&$top=100"
      }
    }
  ],
  "responseShape": {
    "success": {
      "value": [],
      "@local.count": 0,
      "@odata.nextLink": "Returned when another page is available."
    },
    "error": {
      "error": {
        "code": "unauthorized | forbidden | invalid_filter | rate_limited | server_error",
        "message": "Human-readable error message."
      }
    }
  },
  "implementationNotes": [
    "All /v2 endpoints require OriginatingSystemName in $filter.",
    "The PHP API caps $top at 1000 and defaults to 500.",
    "The API serves cached local database records and cached media paths only.",
    "Every customer or agent request is logged in consumer_usage_log.",
    "Friendly /api/... endpoints are documented as planned but are not currently routed by public/index.php."
  ]
}