Entwicklerdokumentation: MCP-Integration

Was ist das Secret Santa Raffle MCP?

Der Secret-Santa-Raffle-MCP-Server (Model Context Protocol) ermöglicht es jedem KI-Assistenten — etwa ChatGPT, Claude oder Gemini —, per natürlicher Sprache automatisch Wichtel-Auslosungen zu erstellen. Statt Formulare auszufüllen, nennt der Nutzer der KI einfach die Teilnehmer, und die KI kommuniziert mit unserem Server, um die Auslosung automatisch zu erzeugen.

Der Server implementiert JSON-RPC 2.0 über HTTPS gemäß der MCP-Spezifikation (Version 2025-06-18). Er stellt drei öffentliche Tools bereit: create_draw, send_invitations_email und get_group_share_message.

Endpunkt & Protokoll

Anfragen werden per JSON-RPC 2.0 über HTTPS gesendet. Die Protokollversion ist 2025-06-18.

Dieser Server stellt zwei Kanäle unter derselben Domain bereit: POST /mcp — der Standardkanal mit dem vollständigen Toolset, für Assistenten wie Claude; und POST /openai/mcp — der OpenAI-konforme Kanal, den die ChatGPT-App nutzt und der nur die drei unten dokumentierten öffentlichen Tools bereitstellt. Beide sprechen dasselbe JSON-RPC-2.0-Protokoll.

Handshake (Initialisierung)

Jeder MCP-Client muss vor dem Aufruf von Tools einen Initialize-Handshake abschließen. Nach Erhalt der Antwort muss der Client eine notifications/initialized-Nachricht senden (ohne id-Feld).

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

Nach der Initialize-Antwort sende: { "jsonrpc": "2.0", "method": "notifications/initialized" } — der Server antwortet mit 202 Accepted und leerem Body.

create_draw — JSON-Schema

Das Haupttool ist create_draw. Es erstellt eine Wichtel-Auslosung mit N Teilnehmern (mindestens 3), verlost sie zufällig unter Beachtung von Ausschlussregeln und liefert eine drawId sowie einen shareCode für weitere Vorgänge zurück.

{
  "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."
    }
  }
}

Feldübersicht

Verfügbare Tools

Typischer Integrationsablauf

Sprach- und Marken-Routing

Der Parameter locale in den Argumenten jedes Tools bestimmt, welche Marke und welche Vorlagen verwendet werden. Gib locale immer an, um die besten Ergebnisse zu erzielen.

Fehlerbehandlung

Der Server liefert Fehler auf Tool-Ebene mit isError: true im Ergebnis zurück und unterscheidet so „Tool ist fehlgeschlagen" von „Tool existiert nicht".