Serveri MCP menugo.al — Udhëzues për integrimin e AI / GPT

Ky dokument është i destinuar për asistentët AI, bot-et GPT dhe integrimet automatike. Përmban detaje të sakta të protokollit, skemat e mjeteve dhe fluksin e autentifikimit.

Informacioni i serverit

Autentifikimi

Të gjitha thirrjet e instrumenteve kërkojnë header-in Authorization.

Opsioni 1: Çelësi API MCP i përdoruesit (rekomandohet)

Authorization: Bearer mk_XXXXXXXXXXXX...  (64 hex-символа)

Është i lidhur me një përdorues specifik. Boti sheh vetëm të dhënat e këtij përdoruesi.

Opsioni 2: Token JWT Cognito

Authorization: Bearer eyJraWQi...  (JWT id_token)

Përftohet përmes POST /auth/login. Skadon pas 1 ore.

Opsioni 3: Admin API Key

Authorization: Bearer <admin_api_key>

Akses i plotë në të gjitha të dhënat. Vetëm për administratorët.

Marrja e tokenit JWT

POST https://api.menugo.al/mcp/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Përgjigjja:

{
  "idToken": "eyJraWQi...",
  "accessToken": "eyJraWQi...",
  "refreshToken": "eyJjdHki...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Protokolli MCP

Inicializimi

POST https://api.menugo.al/mcp
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-bot", "version": "1.0" }
  }
}

Lista e instrumenteve

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

Thirrja e instrumentit

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "имя_инструмента",
    "arguments": { ... }
  }
}

Përgjigjja (sukses): result.content[0].text — string JSON me të dhëna.
Përgjigjja (gabim): result.isError: true, result.content[0].text — teksti i gabimit.

Endpoint-et

Të gjitha shtigjet janë relative ndaj https://api.menugo.al/mcp.

Udhëzuesi i plotë i mjeteve

Nivelet e aksesit

• USER — E disponueshme për të gjithë përdoruesit e autorizuar (të dhënat për llogarinë e tyre)
• ADMIN — Vetëm administratorët (akses i plotë)

Vetëshërbimi

Profilet e përdoruesve

Lokacionet

update_location_profile — fushat që mund të përditësohen: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. Sinkronizohet automatikisht me CDN. Për të ndryshuar domenin, përdorni set_location_domain.

Menu

check_translations — skanon të gjitha kategoritë dhe artikujt e menusë të lokacionit, gjen përkthimet që mungojnë në gjuhët e aktivizuara dhe kthen një raport të detajuar sipas gjuhëve me listën e kategorive dhe artikujve pa përkthime.

update_menu_item — fushat që mund të përditësohen: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. Sinkronizohet automatikisht me CDN.

Porositë

Domenet

CDN

Imazhet

get_image_upload_url — kthen presigned URL (15 min). Pas ngarkimit, pipeline gjeneron automatikisht miniaturat (thumbnails) dhe sinkronizohet me CDN.

S3 (ruajtja)

Enum për bucket: data.meni, cdn.menugo.al, i.menugo.al, o.menugo.al

Cognito

Sistemi

Kontrolli i aksesit

1. Përdoruesit e zakonshëm — vetëm të dhënat e tyre (sipas userId)
2. Aksesi S3 është i kufizuar nga prefiksi users/{userId}/
3. Për veglat e lokacioneve/menysë, userId përcaktohet automatikisht për përdoruesit e zakonshëm (vetëm administratorët e specifikojnë atë)
4. Admin-only: list_users, search_user_by_email, update_user_profile, list_domains, invalidate_cdn_cache, s3_write, s3_delete, cognito_list_users, cognito_get_user, get_system_stats
5. Menaxhimi i çelësave (/api/keys) kërkon Cognito JWT

Kodet e gabimeve

Shembull sesioni

→ POST /  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"bot","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"meni-user-data-mcp","version":"1.0.0"}}}

→ POST /  {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"whoami","arguments":{}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"userId\":\"abc-123\",\"email\":\"user@example.com\"}"}]}}

Konfigurimi i klientit

Claude Desktop

{
  "mcpServers": {
    "meni": {
      "url": "https://api.menugo.al/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

cURL

curl -X POST https://api.menugo.al/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'