openapi: 3.1.0
info:
  title: SurpriseBuddy MCP / Gift Search API
  version: 0.1.0
  description: |
    Curated gift database served via the Model Context Protocol (MCP) over HTTP JSON-RPC 2.0.
    The single endpoint is `POST /api/mcp` which speaks MCP. The four tools below are
    documented here as if they were plain REST operations, for agents that do not yet
    speak MCP (e.g. OpenAI Custom GPT Actions).

    Every result row is country-scoped: `country` is a hard filter and `product_url`
    already contains the affiliate referral parameter — the agent can present the URL
    directly to the end user.
servers:
  - url: https://surprise-buddy.vercel.app
paths:
  /api/mcp:
    post:
      summary: MCP JSON-RPC endpoint (all tool calls go through here)
      operationId: mcp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
components:
  schemas:
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method]
      properties:
        jsonrpc: { type: string, enum: ['2.0'] }
        id: { oneOf: [{ type: integer }, { type: string }, { type: 'null' }] }
        method:
          type: string
          enum: [initialize, tools/list, tools/call, ping]
        params: { type: object }
    JsonRpcResponse:
      type: object
      properties:
        jsonrpc: { type: string, enum: ['2.0'] }
        id: { oneOf: [{ type: integer }, { type: string }, { type: 'null' }] }
        result: { type: object }
        error:
          type: object
          properties:
            code: { type: integer }
            message: { type: string }
    FindGiftsInput:
      type: object
      required: [country]
      properties:
        country:
          type: string
          description: ISO-3166 alpha-2 country code. Hard filter.
          example: DE
        occasion:
          type: string
          example: birthday
        age:
          type: integer
          minimum: 0
          maximum: 120
        gender:
          type: string
          enum: [male, female, unisex]
        budget_min_cents:
          type: integer
          description: Min budget in cents of the country currency.
        budget_max_cents:
          type: integer
        interests:
          type: array
          items: { type: string }
          example: [gaming, technology]
        profession:
          type: string
          example: teacher
        favorite_color:
          type: string
          enum: [red, blue, green, yellow, purple, pink, orange, black, white, gold, silver]
          description: Recipient's favorite color. Only matches gifts with this exact color; color-agnostic gifts are skipped when set.
        limit:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
    GiftHit:
      type: object
      properties:
        id: { type: string, format: uuid }
        title: { type: string }
        description: { type: string }
        why_it_fits: { type: string, nullable: true }
        product_url:
          type: string
          format: uri
          description: Final URL including affiliate referral. Present directly to the user.
        image_url: { type: string, format: uri, nullable: true }
        price_cents: { type: integer }
        price: { type: string, description: 'Decimal string, e.g. "49.99"' }
        currency: { type: string }
        shop: { type: string }
        shop_display_name: { type: string }
        category: { type: string, nullable: true }
        favorite_color:
          type: string
          nullable: true
          enum: [red, blue, green, yellow, purple, pink, orange, black, white, gold, silver, null]
        country_code: { type: string }