openapi: 3.1.0
info:
  title: Big Gay Guide MCP API
  description: |
    Tool catalog for the Big Gay Guide MCP server. All tools are invoked via JSON-RPC 2.0
    over MCP Streamable HTTP (POST https://api.biggay.guide/mcp), not as REST resources on the paths below.

    Protocol flow: initialize → tools/list → tools/call

    Transport: streamable-http (stateless JSON responses; not stdio; not a legacy /sse URL)

    Human documentation: https://biggay.guide/mcp
    MCP registry manifest: https://biggay.guide/.well-known/mcp/server.json
  version: 1.0.0
  contact:
    url: https://biggay.guide/contact
  license:
    name: Proprietary
    url: https://biggay.guide/terms-use

servers:
  - url: https://api.biggay.guide/mcp
    description: MCP Streamable HTTP endpoint (POST only)

paths:
  /mcp:
    post:
      operationId: mcp_jsonrpc
      summary: MCP Streamable HTTP (JSON-RPC 2.0)
      description: |
        Send MCP JSON-RPC messages (initialize, tools/list, tools/call) to this endpoint.
        Required headers: Content-Type application/json, Accept application/json or text/event-stream,
        Mcp-Protocol-Version 2025-03-26. No authentication required.
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON-RPC 2.0 request or batch
      responses:
        "200":
          description: JSON-RPC response (application/json)
          content:
            application/json:
              schema:
                type: object
  /tools/list_cities:
    post:
      operationId: mcp_list_cities
      summary: list_cities
      description: |
        MCP tool: list_cities. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        List active cities with events. Use before search_events when city or country is unknown.
      x-mcp-tool: list_cities
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object
  /tools/list_tags:
    post:
      operationId: mcp_list_tags
      summary: list_tags
      description: |
        MCP tool: list_tags. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        List available event tags for a city, optionally scoped by relativeTime. Use before search_events when filtering by tag.
      x-mcp-tool: list_tags
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "required": [
                "city",
                "countryCode"
              ],
              "properties": {
                "city": {
                  "type": "string",
                  "description": "City name, e.g. \"Melbourne\""
                },
                "countryCode": {
                  "type": "string",
                  "description": "ISO country code, e.g. \"AU\""
                },
                "relativeTime": {
                  "type": "string",
                  "description": "Relative time slug: now, today, tonight, tomorrow, this-weekend, this-week, next-week, future, upcoming, latest, monday–sunday"
                }
              }
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object
  /tools/list_festivals:
    post:
      operationId: mcp_list_festivals
      summary: list_festivals
      description: |
        MCP tool: list_festivals. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        List available festivals for a city, optionally scoped by relativeTime. Use before search_events when filtering by festival.
      x-mcp-tool: list_festivals
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "required": [
                "city",
                "countryCode"
              ],
              "properties": {
                "city": {
                  "type": "string",
                  "description": "City name, e.g. \"Melbourne\""
                },
                "countryCode": {
                  "type": "string",
                  "description": "ISO country code, e.g. \"AU\""
                },
                "relativeTime": {
                  "type": "string",
                  "description": "Relative time slug: now, today, tonight, tomorrow, this-weekend, this-week, next-week, future, upcoming, latest, monday–sunday"
                }
              }
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object
  /tools/search_events:
    post:
      operationId: mcp_search_events
      summary: search_events
      description: |
        MCP tool: search_events. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        Search published gay events in a city by relative time or calendar date range. Optional filters: tags, festivals, featured, search.
      x-mcp-tool: search_events
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "required": [
                "city",
                "countryCode"
              ],
              "properties": {
                "city": {
                  "type": "string",
                  "description": "City name, e.g. \"Melbourne\""
                },
                "countryCode": {
                  "type": "string",
                  "description": "ISO country code, e.g. \"AU\""
                },
                "relativeTime": {
                  "type": "string",
                  "description": "Relative time slug: now, today, tonight, tomorrow, this-weekend, this-week, next-week, future, upcoming, latest, monday–sunday"
                },
                "startDate": {
                  "type": "string",
                  "format": "date",
                  "description": "ISO calendar date YYYY-MM-DD (use with endDate instead of relativeTime)"
                },
                "endDate": {
                  "type": "string",
                  "format": "date",
                  "description": "ISO calendar date YYYY-MM-DD"
                },
                "limit": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 50,
                  "description": "Max results (default 20)"
                },
                "search": {
                  "type": "string",
                  "description": "Optional text search"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Tag filters (AND)"
                },
                "festivals": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Festival filters (exact match)"
                },
                "featured": {
                  "type": "boolean",
                  "description": "When true, return only featured events"
                }
              }
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object
  /tools/get_event:
    post:
      operationId: mcp_get_event
      summary: get_event
      description: |
        MCP tool: get_event. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        Get full public detail for one event by eventId. Pass city and countryCode when known.
      x-mcp-tool: get_event
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "required": [
                "eventId"
              ],
              "properties": {
                "eventId": {
                  "type": "string",
                  "description": "Event ID slug from search_events"
                },
                "city": {
                  "type": "string",
                  "description": "City for geo validation"
                },
                "countryCode": {
                  "type": "string",
                  "description": "Country code for geo validation"
                }
              }
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object
  /tools/search_organisations:
    post:
      operationId: mcp_search_organisations
      summary: search_organisations
      description: |
        MCP tool: search_organisations. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        Search published organisations in a city by category. Use category "gay-bar" for gay bars. Other categories: promoter, venue, festival, city.
      x-mcp-tool: search_organisations
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "required": [
                "city",
                "countryCode",
                "category"
              ],
              "properties": {
                "city": {
                  "type": "string",
                  "description": "City name, e.g. \"Melbourne\""
                },
                "countryCode": {
                  "type": "string",
                  "description": "ISO country code, e.g. \"AU\""
                },
                "category": {
                  "type": "string",
                  "description": "Organisation category: gay-bar, promoter, venue, festival, city"
                },
                "search": {
                  "type": "string",
                  "description": "Optional text search"
                },
                "limit": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100,
                  "description": "Max results (default 50)"
                }
              }
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object
  /tools/get_organisation:
    post:
      operationId: mcp_get_organisation
      summary: get_organisation
      description: |
        MCP tool: get_organisation. Invoke via JSON-RPC tools/call on POST https://api.biggay.guide/mcp, not this HTTP path.
        Get full public detail for one organisation by orgId. Pass city and countryCode when known.
      x-mcp-tool: get_organisation
      x-mcp-transport: streamable-http
      requestBody:
        required: true
        content:
          application/json:
            schema:
            {
              "type": "object",
              "required": [
                "orgId"
              ],
              "properties": {
                "orgId": {
                  "type": "string",
                  "description": "Organisation ID slug from search_organisations"
                },
                "city": {
                  "type": "string",
                  "description": "City for geo validation"
                },
                "countryCode": {
                  "type": "string",
                  "description": "Country code for geo validation"
                }
              }
            }
      responses:
        "200":
          description: Tool result (actual delivery via MCP Streamable HTTP JSON-RPC)
          content:
            application/json:
              schema:
                type: object