Documentació Tècnica: Integració MCP amb IA

Què és el MCP de l'Amic Invisible?

El servidor MCP (Model Context Protocol) de l'Amic Invisible permet que qualsevol assistent d'IA —com ChatGPT, Claude o Gemini— creï sortejos d'intercanvi de regals de manera programàtica utilitzant llenguatge natural. En lloc d'emplenar formularis web, els usuaris simplement diuen a la IA qui hi participa, i la IA es comunica amb el nostre servidor per generar el sorteig automàticament.

El servidor implementa JSON-RPC 2.0 sobre HTTPS, seguint l'especificació MCP (versió 2025-06-18). Exposa tres eines públiques: create_draw, send_invitations_email i get_group_share_message.

Endpoint i Protocol

Les peticions s'envien mitjançant JSON-RPC 2.0 sobre HTTPS. Versió del protocol: 2025-06-18.

Aquest servidor exposa dos canals al mateix domini: POST /mcp — el canal per defecte amb el conjunt complet d'eines, per a assistents com Claude; i POST /openai/mcp — el canal compatible amb OpenAI que fa servir l'app de ChatGPT, que exposa només les tres eines públiques documentades més avall. Tots dos parlen el mateix protocol JSON-RPC 2.0.

Handshake (Inicialització)

Tot client MCP ha de completar un handshake d'inicialització abans d'invocar eines. Després de rebre la resposta, el client ha d'enviar una notificació notifications/initialized (sense camp id).

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

Després de la resposta d'initialize, cal enviar: { "jsonrpc": "2.0", "method": "notifications/initialized" } — el servidor respon 202 Accepted amb el body buit.

create_draw — Esquema JSON

L'eina principal és create_draw. Crea un sorteig d'intercanvi de regals amb N participants (mínim 3), els empareix aleatòriament respectant les exclusions, i retorna un drawId i un shareCode per a operacions posteriors.

{
  "type": "object",
  "required": ["date", "participants"],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Fecha del sorteo, YYYY-MM-DD. Hoy o futuro."
    },
    "participants": {
      "type": "array",
      "minItems": 3,
      "description": "Mínimo 3 participantes. El primero se trata como organizador.",
      "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 de participantes con los que NO debe emparejarse."
          }
        }
      }
    },
    "drawName": {
      "type": "string",
      "maxLength": 255,
      "description": "Opcional. Si se omite, se genera un default como \"Amigo Invisible 2026\"."
    },
    "price": {
      "type": "string",
      "description": "Presupuesto del regalo, texto libre. Ejemplos: \"20€\", \"$25\"."
    },
    "message": {
      "type": "string",
      "description": "Cuerpo del email de invitación. Si se omite, se usa un default localizado."
    },
    "locale": {
      "type": "string",
      "description": "Tag BCP 47 del idioma. Ej: \"es-ES\", \"es-MX\", \"en-GB\". Determina la marca y las plantillas."
    }
  }
}

Referència de camps

Eines disponibles

Flux d'integració típic

Enrutament per idioma i marca

El paràmetre locale als arguments de cada eina determina la marca i les plantilles utilitzades. Inclou-lo sempre per obtenir els millors resultats.

Gestió d'errors

El servidor retorna errors a nivell d'eina amb isError: true al resultat, distingint "l'eina ha fallat" de "l'eina no existeix".