Dokumentazio Teknikoa: MCP Integrazioa AArekin

Zer da Lagun ezkutuaren MCP-a?

Lagun ezkutuaren MCP zerbitzariak (Model Context Protocol) edozein AA laguntzailek —ChatGPT, Claude edo Gemini bezalakoek— oparien trukeko zozketak programatikoki sortzea ahalbidetzen du, hizkuntza naturala erabiliz. Web-formularioak bete beharrean, erabiltzaileek AAri esaten diote nortzuk parte hartzen duten, eta AAk gure zerbitzariarekin komunikatzen da zozketa automatikoki sortzeko.

Zerbitzariak JSON-RPC 2.0 inplementatzen du HTTPS gainean, MCP espezifikazioari jarraituz (2025-06-18 bertsioa). Hiru tresna publiko erakusten ditu: create_draw, send_invitations_email eta get_group_share_message.

Endpointa eta Protokoloa

Eskaerak JSON-RPC 2.0 bidez bidaltzen dira HTTPS gainean. Protokoloaren bertsioa: 2025-06-18.

Zerbitzari honek bi kanal erakusten ditu domeinu berean: POST /mcp — kanal lehenetsia, tresna multzo osoarekin, Claude bezalako laguntzaileentzat; eta POST /openai/mcp — OpenAIrekin bateragarria den kanala, ChatGPTren appak erabiltzen duena, eta behean dokumentatutako hiru tresna publikoak bakarrik erakusten dituena. Biek JSON-RPC 2.0 protokolo bera hitz egiten dute.

Handshakea (Hasieratzea)

MCP bezero orok hasierako handshakea osatu behar du tresnak deitu aurretik. Erantzuna jaso ondoren, bezeroak notifications/initialized jakinarazpena bidali behar du (id eremurik gabe).

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

initialize-ren erantzunaren ondoren, bidali: { "jsonrpc": "2.0", "method": "notifications/initialized" } — zerbitzariak 202 Accepted erantzuten du gorputz hutsarekin.

create_draw — JSON eskema

Tresna nagusia create_draw da. Oparien trukeko zozketa bat sortzen du N parte-hartzailerekin (gutxienez 3), ausaz binakatuz eta baztertzeak errespetatuz, eta drawId eta shareCode bat itzultzen ditu ondorengo eragiketetarako.

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

Eremuen erreferentzia

Tresna erabilgarriak

Integrazio-fluxu tipikoa

Hizkuntzaren eta markaren araberako bideratzea

Tresna bakoitzaren argumentuetako locale parametroak marka eta erabilitako txantiloiak zehazten ditu. Sartu beti emaitzarik onenak lortzeko.

Errore-kudeaketa

Zerbitzariak tresna-mailako erroreak itzultzen ditu emaitzan isError: true adieraziz, "tresnak huts egin du" eta "tresna ez da existitzen" bereiziz.