MCP Sunucusu masamenu.tr — AI / GPT Entegrasyonu için Kılavuz

Bu belge AI asistanları, GPT botları ve otomatik entegrasyonlar içindir. Protokolün kesin detaylarını, araç şemalarını ve kimlik doğrulama akışını içerir.

Sunucu Bilgileri#

Kimlik Doğrulama#

Tüm araç çağrıları Authorization başlığı gerektirir.

Seçenek 1: Kullanıcı MCP API Anahtarı (önerilir)#

Authorization: Bearer mk_XXXXXXXXXXXX...  (64 hex-karakter)

Belirli bir kullanıcıya bağlıdır. Bot yalnızca bu kullanıcının verilerini görür.

Seçenek 2: Cognito JWT Token#

Authorization: Bearer eyJraWQi...  (JWT id_token)

POST /auth/login üzerinden alınır. 1 saat sonra sona erer.

Seçenek 3: Admin API Anahtarı#

Authorization: Bearer <admin_api_key>

Tüm verilere tam erişim. Yalnızca yöneticiler için.

JWT Token Alma#

POST https://api.masamenu.tr/mcp/auth/login
Content-Type: application/json

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

Yanıt:

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

MCP Protokolü#

Başlatma#

POST https://api.masamenu.tr/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" }
  }
}

Araç Listesi#

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

Araç Çağrısı#

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "araç_adı",
    "arguments": { ... }
  }
}

Yanıt (başarı): result.content[0].text — JSON verileri içeren bir dize.
Yanıt (hata): result.isError: true, result.content[0].text — hata metni.

Uç Noktalar#

Tüm yollar https://api.masamenu.tr/mcp ile ilişkilidir.

Araçların Tam Kılavuzu#

Erişim Seviyeleri#

• USER — Tüm yetkilendirilmiş kullanıcılar için erişilebilir (kendi hesap verileri)
• ADMIN — Yalnızca yöneticiler (tam erişim)

Self Servis#

Kullanıcı Profilleri#

Lokasyonlar#

update_location_profile — güncellenebilir alanlar: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. CDN ile otomatik senkronize edilir. Alan adını değiştirmek için set_location_domain kullanın.

Menü#

update_menu_item — güncellenebilir alanlar: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. CDN ile otomatik senkronize edilir.

Siparişler#

Alanlar#

CDN#

Görseller#

get_image_upload_url — presigned URL (15 dk) döndürür. Yüklemeden sonra, pipeline otomatik olarak küçük resimler oluşturur ve CDN ile senkronize eder.

S3 (depolama)#

bucket için Enum: data.meni, cdn.masamenu.tr, i.masamenu.tr, o.masamenu.tr

Cognito#

Sistem#

Erişim Kontrolü#

1. Normal kullanıcılar — yalnızca kendi verileri (userId ile)
2. S3 erişimi users/{userId}/ ön eki ile sınırlıdır
3. Lokasyon/menü araçları için userId normal kullanıcılar için otomatik belirlenir (yalnızca yöneticiler bunu belirtir)
4. Yalnızca yönetici: 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. Anahtar yönetimi (/api/keys) Cognito JWT gerektirir

Hata Kodları#

Oturum Örneği#

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

İstemci Yapılandırması#

Claude Desktop#

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

cURL#

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