MCP שרת meni.ge — מדריך לאינטגרציה עם AI / GPT

מסמך זה מיועד לעוזרי AI, בוטי GPT ואינטגרציות אוטומטיות. מכיל פרטים מדויקים על הפרוטוקול, סכמות כלים וזרימת אימות.

מידע על השרת

מאפיין	ערך
שם השרת	meni-user-data-mcp
פרוטוקול	MCP 2024-11-05 (Streamable HTTP)
תחבורה	HTTP POST (stateless)
URL בסיסי	https://api.meni.ge/mcp
Content-Type	application/json
פורמט	JSON-RPC 2.0

אימות

כל הקריאות לכלים דורשות כותרת Authorization.

אפשרות 1: מפתח MCP API למשתמש (מומלץ)

Authorization: Bearer mk_XXXXXXXXXXXX...  (64 hex-סימנים)

קשור למשתמש ספציפי. הבוט רואה רק את הנתונים של המשתמש הזה.

אפשרות 2: Cognito JWT-טוקן

Authorization: Bearer eyJraWQi...  (JWT id_token)

מתקבל דרך POST /auth/login. פג תוקף לאחר שעה אחת.

אפשרות 3: Admin API Key

Authorization: Bearer <admin_api_key>

גישה מלאה לכל הנתונים. מיועד למנהלים בלבד.

קבלת JWT-טוקן

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

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

תשובה:

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

---

פרוטוקול MCP

אתחול

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

רשימת כלים

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

קריאת כלי

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "שם_הכלי",
    "arguments": { ... }
  }
}

תשובה (הצלחה): result.content[0].text — מחרוזת JSON עם נתונים.
תשובה (שגיאה): result.isError: true, result.content[0].text — טקסט השגיאה.

---

נקודות קצה

שיטה	נתיב	אימות	תיאור
GET	/	אין	מידע על השרת + רשימת כלים
POST	/	כן	MCP JSON-RPC
GET	/health	אין	בדיקה → {"status":"ok"}
POST	/auth/login	אין	התחברות → JWT-טוקנים
GET	/api/keys	JWT בלבד	רשימת מפתחות API
POST	/api/keys	JWT בלבד	יצירת מפתח API
DELETE	/api/keys/{keyId}	JWT בלבד	ביטול מפתח API

כל הנתיבים יחסיים ל-https://api.meni.ge/mcp.

---

מדריך כלים מלא

רמות גישה

• USER — זמין לכל המשתמשים המאומתים (נתונים על חשבונם)
• ADMIN — מנהלים בלבד (גישה מלאה)

---

שירות עצמי

כלי	גישה	ארגומנטים
whoami	USER	אין
my_profile	USER	אין
update_my_profile	USER	fields (object, חובה)
my_locations	USER	אין
my_orders	USER	limit (int, אופציונלי)
my_images	USER	type (enum: all, menu-photos, category-photos, locations, אופציונלי)

פרופילי משתמשים

כלי	גישה	ארגומנטים
list_users	ADMIN	limit (int, אופציונלי)
get_user_profile	USER/ADMIN	userId (string, חובה)
update_user_profile	ADMIN	userId (string, חובה), fields (object, חובה)
search_user_by_email	ADMIN	email (string, חובה)

מיקומים

כלי	גישה	ארגומנטים
list_locations	USER/ADMIN	userId (string, חובה)
get_location_profile	USER/ADMIN	locationId (string, חובה), userId (string, אופציונלי — זיהוי אוטומטי למשתמשים רגילים)
update_location_profile	USER/ADMIN	locationId (string, חובה), fields (object, חובה), userId (string, אופציונלי)
get_location_menu	USER/ADMIN	locationId (string, חובה), language (string, אופציונלי), userId (string, אופציונלי)

update_location_profile — שדות ניתנים לעדכון: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. מסונכרן אוטומטית עם CDN. לשינוי דומיין השתמשו ב-set_location_domain.

תפריט

כלי	גישה	ארגומנטים
list_menu_items	USER/ADMIN	categoryId (string, אופציונלי — לנתונים מלאים), userId (string, אופציונלי)
get_menu_item	USER/ADMIN	itemId (string, חובה), categoryId (string, אופציונלי — חיפוש אוטומטי), userId (string, אופציונלי)
update_menu_item	USER/ADMIN	itemId (string, חובה), fields (object, חובה), categoryId (string, אופציונלי), userId (string, אופציונלי)
create_menu_item	USER/ADMIN	locationId, categoryId, itemId, name (string, חובה), price (number, חובה), nameTranslations (object, אופציונלי), description (string, אופציונלי), status (enum, אופציונלי), sortOrder (number, אופציונלי), userId (string, אופציונלי)
create_menu_category	USER/ADMIN	locationId, categoryId, name (string, חובה), nameTranslations (object, אופציונלי), status (enum, אופציונלי), sortOrder (number, אופציונלי), userId (string, אופציונלי)
update_menu_category	USER/ADMIN	locationId, categoryId (string, חובה), name (string, אופציונלי), nameTranslations (object, אופציונלי), status (enum, אופציונלי), sortOrder (number, אופציונלי), userId (string, אופציונלי)
move_menu_item	USER/ADMIN	locationId, itemId, fromCategoryId, toCategoryId (string, חובה), userId (string, אופציונלי)
merge_categories	USER/ADMIN	locationId, sourceCategoryId, targetCategoryId (string, חובה), keepSourceName (bool, אופציונלי), userId (string, אופציונלי)
delete_menu_category	USER/ADMIN	locationId, categoryId (string, חובה), force (bool, אופציונלי — מחיקה עם פריטים), userId (string, אופציונלי)

update_menu_item — שדות ניתנים לעדכון: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. מסונכרן אוטומטית עם CDN.

הזמנות

כלי	גישה	ארגומנטים
list_orders	USER/ADMIN	userId (אופציונלי), domain (אופציונלי), limit (int, אופציונלי)
get_order	USER/ADMIN	orderId (string, חובה), domain (string, אופציונלי), locationId (string, אופציונלי)

דומיינים

כלי	גישה	ארגומנטים
check_domain_availability	USER	domainName (string, חובה), currentDomainName (string, אופציונלי)
set_location_domain	USER/ADMIN	locationId (string, חובה), domainName (string, חובה)
resolve_domain	USER	domain (string, חובה)
list_domains	ADMIN	prefix (string, אופציונלי)

CDN

כלי	גישה	ארגומנטים
get_cdn_profile	USER	domain (string, חובה)
get_cdn_menu	USER	domain (string, חובה), language (string, חובה)
list_cdn_files	USER	domain (string, חובה)
invalidate_cdn_cache	ADMIN	paths (string[], חובה)

תמונות

כלי	גישה	ארגומנטים
list_user_images	USER/ADMIN	userId (string, חובה), type (enum, אופציונלי)
get_image_upload_url	USER	type (enum: menu-photos, category-photos, locations, חובה), itemId (string, אופציונלי), locationId (string, אופציונלי), filename (string, אופציונלי), contentType (enum, אופציונלי)
delete_image	USER/ADMIN	key (string, חובה — מפתח S3 מלא ב-i.meni.ge)

get_image_upload_url — מחזיר URL חתום מראש (15 דקות). לאחר ההעלאה, הפייפליין מייצר אוטומטית תמונות ממוזערות ומסנכרן עם CDN.

S3 (אחסון)

כלי	גישה	ארגומנטים
s3_read	USER/ADMIN	bucket (enum), key (string) — חובה.
s3_write	ADMIN	bucket (enum: data.meni, cdn.meni.ge, o.meni.ge), key (string), data (object) — חובה.
s3_list	USER/ADMIN	bucket (enum), prefix (string) — חובה., limit (int, אופציונלי)
s3_delete	ADMIN	bucket (enum: data.meni, cdn.meni.ge, o.meni.ge), key (string) — חובה.

Enum עבור bucket: data.meni, cdn.meni.ge, i.meni.ge, o.meni.ge

Cognito

כלי	גישה	ארגומנטים
cognito_list_users	ADMIN	filter (string, אופציונלי), limit (int, אופציונלי)
cognito_get_user	ADMIN	username (string, חובה)

מערכת

כלי	גישה	ארגומנטים
get_system_stats	ADMIN	אין

---

בקרת גישה

1. משתמשים רגילים — רק הנתונים שלהם (לפי userId)
2. גישה ל-S3 מוגבלת לפי קידומת users/{userId}/
3. עבור כלים של מיקומים/תפריטים userId מזוהה אוטומטית למשתמשים רגילים (רק מנהלים מציינים אותו)
4. מנהלים בלבד: 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. ניהול מפתחות (/api/keys) דורש Cognito JWT

קודי שגיאות

HTTP	ערך
200	הצלחה (בדוק result.isError עבור שגיאות כלים)
400	JSON לא תקין או חסר שיטה
401	אימות חסר או לא תקין
405	שיטת HTTP לא נכונה

שגיאת כלי	ערך
🔒 admin access required	נדרשת הרשאת מנהל
🔒 access denied	ניסיון גישה לנתונים של אחרים
missing required argument: <name>	פרמטר חובה לא נמסר
unknown tool: <name>	כלי לא ידוע

---

דוגמת סשן

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

תצורת לקוח

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":{}}}'