MCP Serwer meni.ge — Przewodnik dla integracji AI / GPT

Ten dokument jest przeznaczony dla asystentów AI, botów GPT i automatycznych integracji. Zawiera dokładne szczegóły protokołu, schematy narzędzi i przepływ uwierzytelniania.

Informacje o serwerze

Właściwość	Wartość
Nazwa serwera	meni-user-data-mcp
Protokół	MCP 2024-11-05 (Streamable HTTP)
Transport	HTTP POST (stateless)
Podstawowy URL	`https://api.meni.ge/mcp`
Content-Type	`application/json`
Format	JSON-RPC 2.0

Uwierzytelnianie

Wszystkie wywołania narzędzi wymagają nagłówka Authorization.

Wariant 1: Użytkownikowy klucz MCP API (zalecane)

Authorization: Bearer mk_XXXXXXXXXXXX...  (64 znaki hex)

Powiązany z konkretnym użytkownikiem. Bot widzi tylko dane tego użytkownika.

Wariant 2: Cognito JWT-token

Authorization: Bearer eyJraWQi...  (JWT id_token)

Uzyskiwany przez POST /auth/login. Wygasa po 1 godzinie.

Wariant 3: Admin API Key

Authorization: Bearer <admin_api_key>

Pełny dostęp do wszystkich danych. Tylko dla administratorów.

Uzyskiwanie JWT-tokena

POST https://api.meni.ge/mcp/auth/login
Content-Type: application/json

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

Odpowiedź:

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

Protokół MCP

Inicjalizacja

POST https://api.meni.ge/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 narzędzi

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

Wywołanie narzędzia

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "nazwa_narzędzia",
    "arguments": { ... }
  }
}

Odpowiedź (sukces): result.content[0].text — JSON-string z danymi.
Odpowiedź (błąd): result.isError: true, result.content[0].text — tekst błędu.

Endpointy

Metoda	Ścieżka	Autoryzacja	Opis
`GET`	`/`	Nie	Informacje o serwerze + lista narzędzi
`POST`	`/`	Tak	MCP JSON-RPC
`GET`	`/health`	Nie	Sprawdzenie → `{"status":"ok"}`
`POST`	`/auth/login`	Nie	Logowanie → JWT-tokeny
`GET`	`/api/keys`	Tylko JWT	Lista kluczy API
`POST`	`/api/keys`	Tylko JWT	Utwórz klucz API
`DELETE`	`/api/keys/{keyId}`	Tylko JWT	Cofnij klucz API

Wszystkie ścieżki są względne do https://api.meni.ge/mcp.

Pełny przewodnik po narzędziach

Poziomy dostępu

USER — Dostępne dla wszystkich autoryzowanych użytkowników (dane o swoim koncie)
ADMIN — Tylko administratorzy (pełny dostęp)

Samoobsługa

Narzędzie	Dostęp	Argumenty
`whoami`	USER	brak
`my_profile`	USER	brak
`update_my_profile`	USER	`fields` (object, wymagany)
`my_locations`	USER	brak
`my_orders`	USER	`limit` (int, opc.)
`my_images`	USER	`type` (enum: all, menu-photos, category-photos, locations, opc.)

Profile użytkowników

Narzędzie	Dostęp	Argumenty
`list_users`	ADMIN	`limit` (int, opc.)
`get_user_profile`	USER/ADMIN	`userId` (string, wymagany)
`update_user_profile`	ADMIN	`userId` (string, wymagany), `fields` (object, wymagany)
`search_user_by_email`	ADMIN	`email` (string, wymagany)

Lokacje

Narzędzie	Dostęp	Argumenty
`list_locations`	USER/ADMIN	`userId` (string, wymagany)
`get_location_profile`	USER/ADMIN	`locationId` (string, wymagany), `userId` (string, opc. — auto-określenie dla zwykłych)
`update_location_profile`	USER/ADMIN	`locationId` (string, wymagany), `fields` (object, wymagany), `userId` (string, opc.)
`get_location_menu`	USER/ADMIN	`locationId` (string, wymagany), `language` (string, opc.), `userId` (string, opc.)

update_location_profile — aktualizowane pola: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. Synchronizuje się z CDN automatycznie. Do zmiany domeny użyj set_location_domain.

Narzędzie	Dostęp	Argumenty
`list_menu_items`	USER/ADMIN	`categoryId` (string, opc. — dla pełnych danych), `userId` (string, opc.)
`get_menu_item`	USER/ADMIN	`itemId` (string, wymagany), `categoryId` (string, opc. — auto-wyszukiwanie), `userId` (string, opc.)
`update_menu_item`	USER/ADMIN	`itemId` (string, wymagany), `fields` (object, wymagany), `categoryId` (string, opc.), `userId` (string, opc.)
`create_menu_item`	USER/ADMIN	`locationId`, `categoryId`, `itemId`, `name` (string, wymagany), `price` (number, wymagany), `nameTranslations` (object, opc.), `description` (string, opc.), `status` (enum, opc.), `sortOrder` (number, opc.), `userId` (string, opc.)
`create_menu_category`	USER/ADMIN	`locationId`, `categoryId`, `name` (string, wymagany), `nameTranslations` (object, opc.), `status` (enum, opc.), `sortOrder` (number, opc.), `userId` (string, opc.)
`update_menu_category`	USER/ADMIN	`locationId`, `categoryId` (string, wymagany), `name` (string, opc.), `nameTranslations` (object, opc.), `status` (enum, opc.), `sortOrder` (number, opc.), `userId` (string, opc.)
`move_menu_item`	USER/ADMIN	`locationId`, `itemId`, `fromCategoryId`, `toCategoryId` (string, wymagany), `userId` (string, opc.)
`merge_categories`	USER/ADMIN	`locationId`, `sourceCategoryId`, `targetCategoryId` (string, wymagany), `keepSourceName` (bool, opc.), `userId` (string, opc.)
`delete_menu_category`	USER/ADMIN	`locationId`, `categoryId` (string, wymagany), `force` (bool, opc. — usuń z pozycjami), `userId` (string, opc.)

update_menu_item — aktualizowane pola: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. Synchronizuje się z CDN automatycznie.

Zamówienia

Narzędzie	Dostęp	Argumenty
`list_orders`	USER/ADMIN	`userId` (opc.), `domain` (opc.), `limit` (int, opc.)
`get_order`	USER/ADMIN	`orderId` (string, wymagany), `domain` (string, opc.), `locationId` (string, opc.)

Domeny

Narzędzie	Dostęp	Argumenty
`check_domain_availability`	USER	`domainName` (string, wymagany), `currentDomainName` (string, opc.)
`set_location_domain`	USER/ADMIN	`locationId` (string, wymagany), `domainName` (string, wymagany)
`resolve_domain`	USER	`domain` (string, wymagany)
`list_domains`	ADMIN	`prefix` (string, opc.)

CDN

Narzędzie	Dostęp	Argumenty
`get_cdn_profile`	USER	`domain` (string, wymagany)
`get_cdn_menu`	USER	`domain` (string, wymagany), `language` (string, wymagany)
`list_cdn_files`	USER	`domain` (string, wymagany)
`invalidate_cdn_cache`	ADMIN	`paths` (string[], wymagany)

Obrazy

Narzędzie	Dostęp	Argumenty
`list_user_images`	USER/ADMIN	`userId` (string, wymagany), `type` (enum, opc.)
`get_image_upload_url`	USER	`type` (enum: menu-photos, category-photos, locations, wymagany), `itemId` (string, opc.), `locationId` (string, opc.), `filename` (string, opc.), `contentType` (enum, opc.)
`delete_image`	USER/ADMIN	`key` (string, wymagany — pełny klucz S3 w i.meni.ge)

get_image_upload_url — zwraca presigned URL (15 min). Po przesłaniu pipeline automatycznie generuje miniatury i synchronizuje z CDN.

S3 (przechowywanie)

Narzędzie	Dostęp	Argumenty
`s3_read`	USER/ADMIN	`bucket` (enum), `key` (string) — wymagany
`s3_write`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (string), `data` (object) — wymagany
`s3_list`	USER/ADMIN	`bucket` (enum), `prefix` (string) — wymagany, `limit` (int, opc.)
`s3_delete`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (string) — wymagany

Enum dla bucket: data.meni, cdn.meni.ge, i.meni.ge, o.meni.ge

Cognito

Narzędzie	Dostęp	Argumenty
`cognito_list_users`	ADMIN	`filter` (string, opc.), `limit` (int, opc.)
`cognito_get_user`	ADMIN	`username` (string, wymagany)

System

Narzędzie	Dostęp	Argumenty
`get_system_stats`	ADMIN	brak

Kontrola dostępu

Zwykli użytkownicy — tylko swoje dane (po userId)
Dostęp S3 ograniczony prefiksem users/{userId}/
Dla narzędzi lokalizacji/menu userId auto-określany dla zwykłych użytkowników (tylko admini go wskazują)
Tylko dla adminów: 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
Zarządzanie kluczami (/api/keys) wymaga Cognito JWT

Kody błędów

HTTP	Wartość
`200`	Sukces (sprawdź `result.isError` dla błędów narzędzi)
`400`	Nieprawidłowy JSON lub brak metody
`401`	Brak lub nieprawidłowe uwierzytelnianie
`405`	Nieprawidłowa metoda HTTP

Błąd narzędzia	Wartość
`🔒 admin access required`	Wymagana rola admina
`🔒 access denied`	Próba dostępu do cudzych danych
`missing required argument: <name>`	Nie przekazano wymaganego parametru
`unknown tool: <name>`	Nieznane narzędzie

Przykład sesji

→ 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\"}"}]}}

Konfiguracja klienta

Claude Desktop

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

cURL

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