MCP Serwer — Przewodnik użytkownika

Co to jest?

Serwer MCP (Model Context Protocol) dla meni.ge pozwala na podłączenie asystentów AI (Claude, ChatGPT, Cursor, VS Code Copilot i innych) do danych Twojej restauracji. AI uzyskuje dostęp do menu, lokalizacji, zamówień, obrazów i może nimi zarządzać w Twoim imieniu.

Szybki start

1. Uzyskaj klucz API

Klucz API jest generowany w panelu administracyjnym Twojej restauracji.

Krok po kroku:

Zaloguj się do Panelu administracyjnego pod adresem admin.meni.ge
W menu bocznym otwórz ⚙️ Ustawienia → 🔑 Dostęp
Na stronie znajdź sekcję 🤖 Klucze API MCP
Kliknij przycisk „Wygeneruj nowy klucz”
Wprowadź nazwę klucza (np. „Claude Desktop”, „Cursor”, „Mój GPT”) — to pomoże odróżnić klucze od siebie
Skopiuj klucz od razu — jest wyświetlany tylko raz!

💡 Na tej samej stronie wyświetlany jest URL serwera (https://api.meni.ge/mcp), który również można skopiować jednym kliknięciem.

Zarządzanie kluczami

Możesz utworzyć do 10 kluczy na konto
Każdy klucz można odwołać w dowolnym momencie — przycisk „Odwołaj” obok klucza
Po odwołaniu klucz przestaje działać natychmiast
Jeśli klucz zostanie zgubiony — odwołaj go i utwórz nowy

2. Podłącz asystenta AI

Claude Desktop / Claude Code

Plik konfiguracyjny claude_desktop_config.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer TWÓJ_KLUCZ_API"
      }
    }
  }
}

Cursor

W ustawieniach Cursor → MCP Servers → Add, lub plik .cursor/mcp.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer TWÓJ_KLUCZ_API"
      }
    }
  }
}

VS Code (GitHub Copilot)

W .vscode/mcp.json projektu:

{
  "servers": {
    "meni": {
      "type": "http",
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer TWÓJ_KLUCZ_API"
      }
    }
  }
}

Inne narzędzia AI

Szczegółowe instrukcje krok po kroku dla Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Continue, ChatGPT i innych — w osobnym przewodniku:

👉 Podłączanie narzędzi AI do MCP

Co może asystent AI?

Dla właścicieli restauracji (zwykli użytkownicy)

Komenda	Opis
`whoami`	Pokaż dane konta (userId, email, rola)
`my_profile`	Pobierz swój profil użytkownika
`update_my_profile`	Zaktualizuj pola w swoim profilu
`my_locations`	Lista wszystkich Twoich lokalizacji
`my_orders`	Lista Twoich zamówień
`my_images`	Lista Twoich obrazów (menu, kategorie, lokalizacje)

Profile użytkowników

Komenda	Opis
`get_user_profile`	Pobierz profil użytkownika po userId
`update_user_profile`	Zaktualizuj pola profilu użytkownika
`list_users`	`[ADMIN]` Lista wszystkich użytkowników
`search_user_by_email`	`[ADMIN]` Znajdź użytkownika po email przez Cognito

Praca z lokalizacjami

Komenda	Opis
`list_locations`	Wszystkie lokalizacje użytkownika
`get_location_profile`	Profil lokalizacji (nazwa, adres, godziny pracy, ustawienia)
`update_location_profile`	Zaktualizuj ustawienia lokalizacji (synchronizuje się z CDN automatycznie)
`get_location_menu`	Pełne menu lokalizacji z kategoriami i pozycjami

Praca z menu

Komenda	Opis
`list_menu_items`	Wszystkie pozycje menu (z categoryId — pełne dane, bez — pary item/category ID)
`get_menu_item`	Pobierz pozycję z pełnymi danymi (w tym tłumaczenia, warianty, dodatki)
`update_menu_item`	Zaktualizuj pozycję menu (cena, opis, status, tagi, warianty, dodatki)
`create_menu_item`	Utwórz nową pozycję menu w kategorii
`create_menu_category`	Utwórz nową kategorię menu
`update_menu_category`	Zaktualizuj kategorię (nazwa, tłumaczenia, status, kolejność sortowania)
`move_menu_item`	Przenieś pozycję z jednej kategorii do innej
`merge_categories`	Połącz dwie kategorie (wszystkie pozycje są przenoszone, oryginalna usuwana)
`delete_menu_category`	Usuń kategorię (z `force: true` — razem ze wszystkimi pozycjami)

Zamówienia

Komenda	Opis
`list_orders`	Lista zamówień (po userId lub domenie)
`get_order`	Szczegóły konkretnego zamówienia

Domeny

Komenda	Opis
`check_domain_availability`	Sprawdź dostępność nazwy domeny
`set_location_domain`	Zmień nazwę domeny lokalizacji (aktualizuje CDN i mapowania)
`resolve_domain`	Dowiedz się userId i locationId po domenie
`list_domains`	`[ADMIN]` Lista wszystkich zarejestrowanych domen

CDN (opublikowane dane)

Komenda	Opis
`get_cdn_profile`	Opublikowany profil lokalizacji (na CDN)
`get_cdn_menu`	Opublikowane menu w wybranym języku
`list_cdn_files`	Wszystkie opublikowane pliki domeny
`invalidate_cdn_cache`	`[ADMIN]` Wyczyść cache CloudFront CDN

Obrazy

Komenda	Opis
`list_user_images`	Wszystkie obrazy użytkownika
`get_image_upload_url`	Pobierz presigned URL do przesyłania obrazu do S3 (JPEG/PNG/WebP)
`delete_image`	Usuń obraz (użytkownicy — tylko swoje)

Niskopoziomowy dostęp do S3

Komenda	Opis
`s3_read`	Odczytaj plik z S3 (użytkownicy — tylko swoje)
`s3_write`	`[ADMIN]` Zapisz dane JSON w S3
`s3_list`	Lista plików w S3 (użytkownicy — tylko swój prefiks)
`s3_delete`	`[ADMIN]` Usuń obiekt z S3

Cognito

Komenda	Opis
`cognito_list_users`	`[ADMIN]` Lista użytkowników z Cognito User Pool
`cognito_get_user`	`[ADMIN]` Szczegółowe informacje o użytkowniku Cognito

Statystyki

Komenda	Opis
`get_system_stats`	`[ADMIN]` Statystyki systemowe

Uwierzytelnianie

Serwer obsługuje trzy sposoby autoryzacji:

1. Klucz API (zalecany dla asystentów AI)

Authorization: Bearer twój_64_znakowy_klucz

Klucz jest generowany w panelu administracyjnym. Powiązany z Twoim kontem — AI widzi tylko Twoje dane.

2. Cognito JWT-token

Dla integracji programowej można uzyskać token przez logowanie:

# Uzyskaj token
curl -X POST https://api.meni.ge/mcp/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "twój@email.com", "password": "twoje_hasło"}'

# Odpowiedź zawiera idToken — użyj go:
Authorization: Bearer eyJraWQ...

Token działa przez 1 godzinę, po czym wymaga ponownego logowania.

3. Admin API Key (tylko dla administratorów)

Authorization: Bearer admin_key

Klucz administratora daje pełny dostęp do wszystkich danych wszystkich użytkowników.

Bezpieczeństwo

Każdy klucz API jest powiązany z konkretnym kontem
Zwykli użytkownicy widzą tylko swoje dane
Klucz można odwołać w dowolnym momencie w panelu administracyjnym
Maksymalnie 10 kluczy na konto
Wszystkie zapytania są przesyłane przez HTTPS
Komendy oznaczone [ADMIN] są niedostępne dla zwykłych użytkowników

Przykłady użycia

Poproś AI o aktualizację ceny dania

„Zaktualizuj cenę pozycji „Chaczapuri” w moim menu — zrób 15 lari zamiast 12”

AI wywoła my_locations → get_location_menu → update_menu_item.

Dodaj nową pozycję do menu

„Dodaj do kategorii „Desery” nowe danie „Czurczchela” za 8 lari”

AI wywoła my_locations → get_location_menu → create_menu_item.

Utwórz nową kategorię

„Utwórz kategorię „Napoje” z tłumaczeniami na gruziński i angielski”

AI wywoła create_menu_category z nameTranslations.

Przenieś danie między kategoriami

„Przenieś „Lemoniadę” z „Zimne napoje” do „Bezalkoholowe””

AI wywoła move_menu_item z wskazaniem kategorii źródłowej i docelowej.

Zobacz zamówienia na dziś

„Pokaż moje zamówienia na dziś”

AI wywoła my_orders i przefiltruje po dacie.

Sprawdź opublikowane menu

„Jak wygląda moje menu w języku rosyjskim dla odwiedzających?”

AI wywoła resolve_domain → get_cdn_menu z językiem ru.

Zmień domenę restauracji

„Sprawdź, czy domena my-restaurant jest dostępna, a jeśli tak — ustaw ją”

AI wywoła check_domain_availability → set_location_domain.

Prześlij zdjęcie dania

„Daj mi link do przesłania zdjęcia do dania X”

AI wywoła get_image_upload_url i zwróci presigned URL do przesyłania.

API-endpointy

Metoda	URL	Opis
`GET`	`https://api.meni.ge/mcp`	Informacje o serwerze + lista narzędzi
`POST`	`https://api.meni.ge/mcp`	MCP JSON-RPC (główny protokół)
`GET`	`https://api.meni.ge/mcp/health`	Sprawdzenie działania
`POST`	`https://api.meni.ge/mcp/auth/login`	Logowanie → JWT-tokeny
`GET`	`https://api.meni.ge/mcp/api/keys`	Lista Twoich kluczy API
`POST`	`https://api.meni.ge/mcp/api/keys`	Utwórz nowy klucz API
`DELETE`	`https://api.meni.ge/mcp/api/keys/{id}`	Odwołaj klucz API

Zarządzanie kluczami

Przegląd kluczy

W panelu administracyjnym → Ustawienia → Dostęp → Klucze API MCP. Lub przez API:

curl https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

Tworzenie klucza

curl -X POST https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop"}'

Odpowiedź zawiera pole key — to jest Twój klucz. Zapisz go!

Odwołanie klucza

curl -X DELETE https://api.meni.ge/mcp/api/keys/mk_abc123 \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

⚠️ Tworzenie i odwoływanie kluczy wymaga Cognito JWT-token (nie klucza API). Użyj panelu administracyjnego — to prostsze.

Rozwiązywanie problemów

Problem	Rozwiązanie
`401 Unauthorized`	Sprawdź klucz API. Jeśli został odwołany — utwórz nowy
`403 user identity required`	Użyj Cognito JWT do zarządzania kluczami
`🔒 admin access required`	Komenda dostępna tylko dla administratorów
`🔒 access denied`	Próbujesz uzyskać dane innego użytkownika
Klucz nie działa	Sprawdź, czy klucz nie został odwołany, i format: `Bearer <klucz>`