Dokumentacja dla deweloperów: integracja MCP

Czym jest Secret Santa Raffle MCP?

Serwer Secret Santa Raffle MCP (Model Context Protocol) umożliwia dowolnemu asystentowi AI — takiemu jak ChatGPT, Claude czy Gemini — programowe tworzenie losowań wymiany prezentów za pomocą języka naturalnego. Zamiast wypełniać formularze na stronie, użytkownik po prostu mówi AI, kto bierze udział, a AI komunikuje się z naszym serwerem, by automatycznie wygenerować losowanie.

Serwer implementuje JSON-RPC 2.0 przez HTTPS, zgodnie ze specyfikacją MCP (wersja 2025-06-18). Udostępnia trzy publiczne narzędzia: create_draw, send_invitations_email i get_group_share_message.

Endpoint i protokół

Żądania są wysyłane przez JSON-RPC 2.0 przez HTTPS. Wersja protokołu to 2025-06-18.

Ten serwer udostępnia dwa kanały na tej samej domenie: POST /mcp — domyślny kanał z pełnym zestawem narzędzi, dla asystentów takich jak Claude; oraz POST /openai/mcp — kanał zgodny z OpenAI, używany przez aplikację ChatGPT, który udostępnia tylko trzy publiczne narzędzia opisane poniżej. Oba używają tego samego protokołu JSON-RPC 2.0.

Uzgadnianie połączenia (Initialize)

Każdy klient MCP musi zakończyć proces uzgadniania initialize przed wywołaniem narzędzi. Po otrzymaniu odpowiedzi klient musi wysłać wiadomość notifications/initialized (bez pola id).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Po odpowiedzi initialize wyślij: { "jsonrpc": "2.0", "method": "notifications/initialized" } — serwer odpowiada 202 Accepted z pustym ciałem odpowiedzi.

create_draw — schemat JSON

Głównym narzędziem jest create_draw. Tworzy ono losowanie wymiany prezentów z N uczestnikami (minimum 3), dopasowuje ich losowo z zachowaniem ograniczeń wykluczeń i zwraca drawId oraz shareCode do dalszych operacji.

{
  "type": "object",
  "required": ["date", "participants"],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Draw date, YYYY-MM-DD. Today or future."
    },
    "participants": {
      "type": "array",
      "minItems": 3,
      "description": "Minimum 3 participants. The first is treated as the organiser.",
      "items": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "maxLength": 255 },
          "email": { "type": "string", "format": "email" },
          "exclusions": {
            "type": "array",
            "items": { "type": "string", "format": "email" },
            "description": "Emails of participants this person must NOT be matched with."
          }
        }
      }
    },
    "drawName": {
      "type": "string",
      "maxLength": 255,
      "description": "Optional. Defaults to e.g. \"Secret Santa 2026\"."
    },
    "price": {
      "type": "string",
      "description": "Gift budget, free text. Examples: \"£25\", \"$30\"."
    },
    "message": {
      "type": "string",
      "description": "Invitation email body. If omitted, a localised default is used. Placeholder \"ParticipantX\" replaced with the recipient's name."
    },
    "locale": {
      "type": "string",
      "description": "BCP 47 language tag. E.g. \"en-GB\", \"es-ES\", \"es-MX\". Determines brand and templates."
    }
  }
}

Opis pól

Dostępne narzędzia

Typowy przepływ integracji

Kierowanie po języku i marce

Parametr locale w argumentach każdego narzędzia określa, która marka i szablony są używane. Zawsze podawaj locale, by uzyskać najlepsze rezultaty.

Obsługa błędów

Serwer zwraca błędy na poziomie narzędzia z isError: true w wyniku, odróżniając „narzędzie zawiodło” od „narzędzie nie istnieje”.