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-ით. იწურება 1 საათში.

ვარიანტი 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` (ობიექტი, სავალდებულო)
`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` (სტრიქონი, სავალდებულო)
`update_user_profile`	ADMIN	`userId` (სტრიქონი, სავალდებულო), `fields` (ობიექტი, სავალდებულო)
`search_user_by_email`	ADMIN	`email` (სტრიქონი, სავალდებულო)

ლოკაციები

ინსტრუმენტი	წვდომა	არგუმენტები
`list_locations`	USER/ADMIN	`userId` (სტრიქონი, სავალდებულო)
`get_location_profile`	USER/ADMIN	`locationId` (სტრიქონი, სავალდებულო), `userId` (სტრიქონი, არჩევითი — ავტომატური განსაზღვრა ჩვეულებრივი მომხმარებლებისთვის)
`update_location_profile`	USER/ADMIN	`locationId` (სტრიქონი, სავალდებულო), `fields` (ობიექტი, სავალდებულო), `userId` (სტრიქონი, არჩევითი)
`get_location_menu`	USER/ADMIN	`locationId` (სტრიქონი, სავალდებულო), `language` (სტრიქონი, არჩევითი), `userId` (სტრიქონი, არჩევითი)

update_location_profile — განახლებადი ველები: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. სინქრონიზირდება CDN-თან ავტომატურად. დომენის შესაცვლელად გამოიყენეთ set_location_domain.

მენიუ

ინსტრუმენტი	წვდომა	არგუმენტები
`list_menu_items`	USER/ADMIN	`categoryId` (სტრიქონი, არჩევითი — სრული მონაცემებისთვის), `userId` (სტრიქონი, არჩევითი)
`get_menu_item`	USER/ADMIN	`itemId` (სტრიქონი, სავალდებულო), `categoryId` (სტრიქონი, არჩევითი — ავტომატური ძიება), `userId` (სტრიქონი, არჩევითი)
`update_menu_item`	USER/ADMIN	`itemId` (სტრიქონი, სავალდებულო), `fields` (ობიექტი, სავალდებულო), `categoryId` (სტრიქონი, არჩევითი), `userId` (სტრიქონი, არჩევითი)
`create_menu_item`	USER/ADMIN	`locationId`, `categoryId`, `itemId`, `name` (სტრიქონი, სავალდებულო), `price` (რიცხვი, სავალდებულო), `nameTranslations` (ობიექტი, არჩევითი), `description` (სტრიქონი, არჩევითი), `status` (enum, არჩევითი), `sortOrder` (რიცხვი, არჩევითი), `userId` (სტრიქონი, არჩევითი)
`create_menu_category`	USER/ADMIN	`locationId`, `categoryId`, `name` (სტრიქონი, სავალდებულო), `nameTranslations` (ობიექტი, არჩევითი), `status` (enum, არჩევითი), `sortOrder` (რიცხვი, არჩევითი), `userId` (სტრიქონი, არჩევითი)
`update_menu_category`	USER/ADMIN	`locationId`, `categoryId` (სტრიქონი, სავალდებულო), `name` (სტრიქონი, არჩევითი), `nameTranslations` (ობიექტი, არჩევითი), `status` (enum, არჩევითი), `sortOrder` (რიცხვი, არჩევითი), `userId` (სტრიქონი, არჩევითი)
`move_menu_item`	USER/ADMIN	`locationId`, `itemId`, `fromCategoryId`, `toCategoryId` (სტრიქონი, სავალდებულო), `userId` (სტრიქონი, არჩევითი)
`merge_categories`	USER/ADMIN	`locationId`, `sourceCategoryId`, `targetCategoryId` (სტრიქონი, სავალდებულო), `keepSourceName` (bool, არჩევითი), `userId` (სტრიქონი, არჩევითი)
`delete_menu_category`	USER/ADMIN	`locationId`, `categoryId` (სტრიქონი, სავალდებულო), `force` (bool, არჩევითი — წაშლა პოზიციებით), `userId` (სტრიქონი, არჩევითი)

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` (სტრიქონი, სავალდებულო), `domain` (სტრიქონი, არჩევითი), `locationId` (სტრიქონი, არჩევითი)

დომენები

ინსტრუმენტი	წვდომა	არგუმენტები
`check_domain_availability`	USER	`domainName` (სტრიქონი, სავალდებულო), `currentDomainName` (სტრიქონი, არჩევითი)
`set_location_domain`	USER/ADMIN	`locationId` (სტრიქონი, სავალდებულო), `domainName` (სტრიქონი, სავალდებულო)
`resolve_domain`	USER	`domain` (სტრიქონი, სავალდებულო)
`list_domains`	ADMIN	`prefix` (სტრიქონი, არჩევითი)

CDN

ინსტრუმენტი	წვდომა	არგუმენტები
`get_cdn_profile`	USER	`domain` (სტრიქონი, სავალდებულო)
`get_cdn_menu`	USER	`domain` (სტრიქონი, სავალდებულო), `language` (სტრიქონი, სავალდებულო)
`list_cdn_files`	USER	`domain` (სტრიქონი, სავალდებულო)
`invalidate_cdn_cache`	ADMIN	`paths` (სტრიქონების მასივი, სავალდებულო)

სურათები

ინსტრუმენტი	წვდომა	არგუმენტები
`list_user_images`	USER/ADMIN	`userId` (სტრიქონი, სავალდებულო), `type` (enum, არჩევითი)
`get_image_upload_url`	USER	`type` (enum: menu-photos, category-photos, locations, სავალდებულო), `itemId` (სტრიქონი, არჩევითი), `locationId` (სტრიქონი, არჩევითი), `filename` (სტრიქონი, არჩევითი), `contentType` (enum, არჩევითი)
`delete_image`	USER/ADMIN	`key` (სტრიქონი, სავალდებულო — სრული S3-გასაღები i.meni.ge-ში)

get_image_upload_url — აბრუნებს presigned URL-ს (15 წთ). ატვირთვის შემდეგ პაიპლაინი ავტომატურად გენერირებს მინიატურებს და სინქრონიზირდება CDN-თან.

S3 (საცავი)

ინსტრუმენტი	წვდომა	არგუმენტები
`s3_read`	USER/ADMIN	`bucket` (enum), `key` (სტრიქონი) — სავალდებულო
`s3_write`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (სტრიქონი), `data` (ობიექტი) — სავალდებულო
`s3_list`	USER/ADMIN	`bucket` (enum), `prefix` (სტრიქონი) — სავალდებულო, `limit` (int, არჩევითი)
`s3_delete`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (სტრიქონი) — სავალდებულო

Enum bucket-ისთვის: data.meni, cdn.meni.ge, i.meni.ge, o.meni.ge

Cognito

ინსტრუმენტი	წვდომა	არგუმენტები
`cognito_list_users`	ADMIN	`filter` (სტრიქონი, არჩევითი), `limit` (int, არჩევითი)
`cognito_get_user`	ADMIN	`username` (სტრიქონი, სავალდებულო)

სისტემა

ინსტრუმენტი	წვდომა	არგუმენტები
`get_system_stats`	ADMIN	არა

წვდომის კონტროლი

ჩვეულებრივი მომხმარებლები — მხოლოდ საკუთარი მონაცემები (userId-ის მიხედვით)
S3 წვდომა შეზღუდულია პრეფიქსით users/{userId}/
ლოკაციების/მენიუს ინსტრუმენტებისთვის userId ავტომატურად განისაზღვრება ჩვეულებრივი მომხმარებლებისთვის (მხოლოდ ადმინისტრატორები მიუთითებენ მას)
მხოლოდ ადმინისტრატორებისთვის: 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
გასაღებების მართვა (/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":{}}}'