MCP Sunucusu meni.ge — 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

Özellik	Değer
Sunucu Adı	meni-user-data-mcp
Protokol	MCP 2024-11-05 (Streamable HTTP)
Taşıma	HTTP POST (stateless)
Temel URL	`https://api.meni.ge/mcp`
Content-Type	`application/json`
Format	JSON-RPC 2.0

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.meni.ge/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.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" }
  }
}

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

Metod	Yol	Yetkilendirme	Açıklama
`GET`	`/`	Yok	Sunucu bilgisi + araç listesi
`POST`	`/`	Evet	MCP JSON-RPC
`GET`	`/health`	Yok	Kontrol → `{"status":"ok"}`
`POST`	`/auth/login`	Yok	Giriş → JWT tokenleri
`GET`	`/api/keys`	Yalnızca JWT	API anahtarları listesi
`POST`	`/api/keys`	Yalnızca JWT	API anahtarı oluştur
`DELETE`	`/api/keys/{keyId}`	Yalnızca JWT	API anahtarını iptal et

Tüm yollar https://api.meni.ge/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

Araç	Erişim	Argümanlar
`whoami`	USER	yok
`my_profile`	USER	yok
`update_my_profile`	USER	`fields` (object, zorunlu)
`my_locations`	USER	yok
`my_orders`	USER	`limit` (int, ops.)
`my_images`	USER	`type` (enum: all, menu-photos, category-photos, locations, ops.)

Kullanıcı Profilleri

Araç	Erişim	Argümanlar
`list_users`	ADMIN	`limit` (int, ops.)
`get_user_profile`	USER/ADMIN	`userId` (string, zorunlu)
`update_user_profile`	ADMIN	`userId` (string, zorunlu), `fields` (object, zorunlu)
`search_user_by_email`	ADMIN	`email` (string, zorunlu)

Lokasyonlar

Araç	Erişim	Argümanlar
`list_locations`	USER/ADMIN	`userId` (string, zorunlu)
`get_location_profile`	USER/ADMIN	`locationId` (string, zorunlu), `userId` (string, ops. — normal kullanıcılar için otomatik belirleme)
`update_location_profile`	USER/ADMIN	`locationId` (string, zorunlu), `fields` (object, zorunlu), `userId` (string, ops.)
`get_location_menu`	USER/ADMIN	`locationId` (string, zorunlu), `language` (string, ops.), `userId` (string, ops.)

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ü

Araç	Erişim	Argümanlar
`list_menu_items`	USER/ADMIN	`categoryId` (string, ops. — tam veriler için), `userId` (string, ops.)
`get_menu_item`	USER/ADMIN	`itemId` (string, zorunlu), `categoryId` (string, ops. — otomatik arama), `userId` (string, ops.)
`update_menu_item`	USER/ADMIN	`itemId` (string, zorunlu), `fields` (object, zorunlu), `categoryId` (string, ops.), `userId` (string, ops.)
`create_menu_item`	USER/ADMIN	`locationId`, `categoryId`, `itemId`, `name` (string, zorunlu), `price` (number, zorunlu), `nameTranslations` (object, ops.), `description` (string, ops.), `status` (enum, ops.), `sortOrder` (number, ops.), `userId` (string, ops.)
`create_menu_category`	USER/ADMIN	`locationId`, `categoryId`, `name` (string, zorunlu), `nameTranslations` (object, ops.), `status` (enum, ops.), `sortOrder` (number, ops.), `userId` (string, ops.)
`update_menu_category`	USER/ADMIN	`locationId`, `categoryId` (string, zorunlu), `name` (string, ops.), `nameTranslations` (object, ops.), `status` (enum, ops.), `sortOrder` (number, ops.), `userId` (string, ops.)
`move_menu_item`	USER/ADMIN	`locationId`, `itemId`, `fromCategoryId`, `toCategoryId` (string, zorunlu), `userId` (string, ops.)
`merge_categories`	USER/ADMIN	`locationId`, `sourceCategoryId`, `targetCategoryId` (string, zorunlu), `keepSourceName` (bool, ops.), `userId` (string, ops.)
`delete_menu_category`	USER/ADMIN	`locationId`, `categoryId` (string, zorunlu), `force` (bool, ops. — öğelerle birlikte sil), `userId` (string, ops.)

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

Siparişler

Araç	Erişim	Argümanlar
`list_orders`	USER/ADMIN	`userId` (ops.), `domain` (ops.), `limit` (int, ops.)
`get_order`	USER/ADMIN	`orderId` (string, zorunlu), `domain` (string, ops.), `locationId` (string, ops.)

Alanlar

Araç	Erişim	Argümanlar
`check_domain_availability`	USER	`domainName` (string, zorunlu), `currentDomainName` (string, ops.)
`set_location_domain`	USER/ADMIN	`locationId` (string, zorunlu), `domainName` (string, zorunlu)
`resolve_domain`	USER	`domain` (string, zorunlu)
`list_domains`	ADMIN	`prefix` (string, ops.)

CDN

Araç	Erişim	Argümanlar
`get_cdn_profile`	USER	`domain` (string, zorunlu)
`get_cdn_menu`	USER	`domain` (string, zorunlu), `language` (string, zorunlu)
`list_cdn_files`	USER	`domain` (string, zorunlu)
`invalidate_cdn_cache`	ADMIN	`paths` (string[], zorunlu)

Görseller

Araç	Erişim	Argümanlar
`list_user_images`	USER/ADMIN	`userId` (string, zorunlu), `type` (enum, ops.)
`get_image_upload_url`	USER	`type` (enum: menu-photos, category-photos, locations, zorunlu), `itemId` (string, ops.), `locationId` (string, ops.), `filename` (string, ops.), `contentType` (enum, ops.)
`delete_image`	USER/ADMIN	`key` (string, zorunlu — i.meni.ge'deki tam S3 anahtarı)

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)

Araç	Erişim	Argümanlar
`s3_read`	USER/ADMIN	`bucket` (enum), `key` (string) — zorunlu
`s3_write`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (string), `data` (object) — zorunlu
`s3_list`	USER/ADMIN	`bucket` (enum), `prefix` (string) — zorunlu, `limit` (int, ops.)
`s3_delete`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (string) — zorunlu

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

Cognito

Araç	Erişim	Argümanlar
`cognito_list_users`	ADMIN	`filter` (string, ops.), `limit` (int, ops.)
`cognito_get_user`	ADMIN	`username` (string, zorunlu)

Sistem

Araç	Erişim	Argümanlar
`get_system_stats`	ADMIN	yok

Erişim Kontrolü

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

Hata Kodları

HTTP	Anlamı
`200`	Başarılı (araç hataları için `result.isError` kontrol edin)
`400`	Geçersiz JSON veya eksik metod
`401`	Eksik veya geçersiz kimlik doğrulama
`405`	Yanlış HTTP metodu

Araç Hatası	Anlamı
`🔒 admin access required`	Yönetici rolü gereklidir
`🔒 access denied`	Başka birinin verilerine erişim denemesi
`missing required argument: <name>`	Zorunlu parametre iletilmedi
`unknown tool: <name>`	Bilinmeyen araç

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