MCP Máy chủ meni.ge — Hướng dẫn tích hợp AI / GPT

Tài liệu này dành cho trợ lý AI, bot GPT và tích hợp tự động. Chứa các chi tiết chính xác về giao thức, sơ đồ công cụ và luồng xác thực.

Thông tin máy chủ

Thuộc tính	Giá trị
Tên máy chủ	meni-user-data-mcp
Giao thức	MCP 2024-11-05 (Streamable HTTP)
Giao vận	HTTP POST (stateless)
URL cơ bản	https://api.meni.ge/mcp
Content-Type	application/json
Định dạng	JSON-RPC 2.0

Xác thực

Tất cả các cuộc gọi công cụ yêu cầu tiêu đề Authorization.

Phương án 1: Khóa API MCP người dùng (khuyến nghị)

Authorization: Bearer mk_XXXXXXXXXXXX...  (64 ký tự hex)

Liên kết với người dùng cụ thể. Bot chỉ thấy dữ liệu của người dùng này.

Phương án 2: Cognito JWT-token

Authorization: Bearer eyJraWQi...  (JWT id_token)

Nhận được qua POST /auth/login. Hết hạn sau 1 giờ.

Phương án 3: Admin API Key

Authorization: Bearer <admin_api_key>

Truy cập đầy đủ vào tất cả dữ liệu. Chỉ dành cho quản trị viên.

Nhận JWT-token

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

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

Phản hồi:

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

---

Giao thức MCP

Khởi tạo

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

Danh sách công cụ

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

Gọi công cụ

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "имя_инструмента",
    "arguments": { ... }
  }
}

Phản hồi (thành công): result.content[0].text — Chuỗi JSON với dữ liệu.
Phản hồi (lỗi): result.isError: true, result.content[0].text — văn bản lỗi.

---

Điểm cuối

Phương thức	Đường dẫn	Xác thực	Mô tả
GET	/	Không	Thông tin máy chủ + danh sách công cụ
POST	/	Có	MCP JSON-RPC
GET	/health	Không	Kiểm tra → {"status":"ok"}
POST	/auth/login	Không	Đăng nhập → JWT-tokens
GET	/api/keys	Chỉ JWT	Danh sách khóa API
POST	/api/keys	Chỉ JWT	Tạo khóa API
DELETE	/api/keys/{keyId}	Chỉ JWT	Thu hồi khóa API

Tất cả các đường dẫn tương đối với https://api.meni.ge/mcp.

---

Hướng dẫn đầy đủ về công cụ

Mức độ truy cập

• USER — Dành cho tất cả người dùng đã xác thực (dữ liệu tài khoản của mình)
• ADMIN — Chỉ dành cho quản trị viên (truy cập đầy đủ)

---

Tự phục vụ

Công cụ	Truy cập	Tham số
whoami	USER	không
my_profile	USER	không
update_my_profile	USER	fields (object, bắt buộc)
my_locations	USER	không
my_orders	USER	limit (int, tùy chọn)
my_images	USER	type (enum: all, menu-photos, category-photos, locations, tùy chọn)

Hồ sơ người dùng

Công cụ	Truy cập	Tham số
list_users	ADMIN	limit (int, tùy chọn)
get_user_profile	USER/ADMIN	userId (string, bắt buộc)
update_user_profile	ADMIN	userId (string, bắt buộc), fields (object, bắt buộc)
search_user_by_email	ADMIN	email (string, bắt buộc)

Địa điểm

Công cụ	Truy cập	Tham số
list_locations	USER/ADMIN	userId (string, bắt buộc)
get_location_profile	USER/ADMIN	locationId (string, bắt buộc), userId (string, tùy chọn — tự động xác định cho người dùng thông thường)
update_location_profile	USER/ADMIN	locationId (string, bắt buộc), fields (object, bắt buộc), userId (string, tùy chọn)
get_location_menu	USER/ADMIN	locationId (string, bắt buộc), language (string, tùy chọn), userId (string, tùy chọn)

update_location_profile — các trường có thể cập nhật: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. Đồng bộ hóa với CDN tự động. Để thay đổi tên miền, sử dụng set_location_domain.

Thực đơn

Công cụ	Truy cập	Tham số
list_menu_items	USER/ADMIN	categoryId (string, tùy chọn — cho dữ liệu đầy đủ), userId (string, tùy chọn)
get_menu_item	USER/ADMIN	itemId (string, bắt buộc), categoryId (string, tùy chọn — tự động tìm kiếm), userId (string, tùy chọn)
update_menu_item	USER/ADMIN	itemId (string, bắt buộc), fields (object, bắt buộc), categoryId (string, tùy chọn), userId (string, tùy chọn)
create_menu_item	USER/ADMIN	locationId, categoryId, itemId, name (string, bắt buộc), price (number, bắt buộc), nameTranslations (object, tùy chọn), description (string, tùy chọn), status (enum, tùy chọn), sortOrder (number, tùy chọn), userId (string, tùy chọn)
create_menu_category	USER/ADMIN	locationId, categoryId, name (string, bắt buộc), nameTranslations (object, tùy chọn), status (enum, tùy chọn), sortOrder (number, tùy chọn), userId (string, tùy chọn)
update_menu_category	USER/ADMIN	locationId, categoryId (string, bắt buộc), name (string, tùy chọn), nameTranslations (object, tùy chọn), status (enum, tùy chọn), sortOrder (number, tùy chọn), userId (string, tùy chọn)
move_menu_item	USER/ADMIN	locationId, itemId, fromCategoryId, toCategoryId (string, bắt buộc), userId (string, tùy chọn)
merge_categories	USER/ADMIN	locationId, sourceCategoryId, targetCategoryId (string, bắt buộc), keepSourceName (bool, tùy chọn), userId (string, tùy chọn)
delete_menu_category	USER/ADMIN	locationId, categoryId (string, bắt buộc), force (bool, tùy chọn — xóa cùng với các mục), userId (string, tùy chọn)

update_menu_item — các trường có thể cập nhật: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. Đồng bộ hóa với CDN tự động.

Đơn hàng

Công cụ	Truy cập	Tham số
list_orders	USER/ADMIN	userId (tùy chọn), domain (tùy chọn), limit (int, tùy chọn)
get_order	USER/ADMIN	orderId (string, bắt buộc), domain (string, tùy chọn), locationId (string, tùy chọn)

Tên miền

Công cụ	Truy cập	Tham số
check_domain_availability	USER	domainName (string, bắt buộc), currentDomainName (string, tùy chọn)
set_location_domain	USER/ADMIN	locationId (string, bắt buộc), domainName (string, bắt buộc)
resolve_domain	USER	domain (string, bắt buộc)
list_domains	ADMIN	prefix (string, tùy chọn)

CDN

Công cụ	Truy cập	Tham số
get_cdn_profile	USER	domain (string, bắt buộc)
get_cdn_menu	USER	domain (string, bắt buộc), language (string, bắt buộc)
list_cdn_files	USER	domain (string, bắt buộc)
invalidate_cdn_cache	ADMIN	paths (string[], bắt buộc)

Hình ảnh

Công cụ	Truy cập	Tham số
list_user_images	USER/ADMIN	userId (string, bắt buộc), type (enum, tùy chọn)
get_image_upload_url	USER	type (enum: menu-photos, category-photos, locations, bắt buộc), itemId (string, tùy chọn), locationId (string, tùy chọn), filename (string, tùy chọn), contentType (enum, tùy chọn)
delete_image	USER/ADMIN	key (string, bắt buộc — khóa S3 đầy đủ trong i.meni.ge)

get_image_upload_url — trả về URL presigned (15 phút). Sau khi tải lên, pipeline tự động tạo hình thu nhỏ và đồng bộ hóa với CDN.

S3 (lưu trữ)

Công cụ	Truy cập	Tham số
s3_read	USER/ADMIN	bucket (enum), key (string) — bắt buộc
s3_write	ADMIN	bucket (enum: data.meni, cdn.meni.ge, o.meni.ge), key (string), data (object) — bắt buộc
s3_list	USER/ADMIN	bucket (enum), prefix (string) — bắt buộc, limit (int, tùy chọn)
s3_delete	ADMIN	bucket (enum: data.meni, cdn.meni.ge, o.meni.ge), key (string) — bắt buộc

Enum cho bucket: data.meni, cdn.meni.ge, i.meni.ge, o.meni.ge

Cognito

Công cụ	Truy cập	Tham số
cognito_list_users	ADMIN	filter (string, tùy chọn), limit (int, tùy chọn)
cognito_get_user	ADMIN	username (string, bắt buộc)

Hệ thống

Công cụ	Truy cập	Tham số
get_system_stats	ADMIN	không

---

Kiểm soát truy cập

1. Người dùng thông thường — chỉ dữ liệu của mình (theo userId)
2. Truy cập S3 bị giới hạn bởi tiền tố users/{userId}/
3. Đối với công cụ địa điểm/thực đơn userId tự động xác định cho người dùng thông thường (chỉ quản trị viên chỉ định nó)
4. Chỉ quản trị viên: 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. Quản lý khóa (/api/keys) yêu cầu Cognito JWT

Mã lỗi

HTTP	Giá trị
200	Thành công (kiểm tra result.isError cho lỗi công cụ)
400	JSON không hợp lệ hoặc thiếu phương thức
401	Thiếu hoặc xác thực không hợp lệ
405	Phương thức HTTP không hợp lệ

Lỗi công cụ	Giá trị
🔒 admin access required	Yêu cầu vai trò quản trị viên
🔒 access denied	Cố gắng truy cập dữ liệu của người khác
missing required argument: <name>	Tham số bắt buộc không được truyền
unknown tool: <name>	Công cụ không xác định

---

Ví dụ phiên

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

Cấu hình khách hàng

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