MCP Server — Hướng dẫn sử dụng

Nó là gì?

MCP server (Model Context Protocol) cho meni.ge cho phép kết nối các trợ lý AI (Claude, ChatGPT, Cursor, VS Code Copilot, v.v.) với dữ liệu nhà hàng của bạn. AI có quyền truy cập vào thực đơn, địa điểm, đơn hàng, hình ảnh và có thể quản lý chúng thay mặt bạn.

Bắt đầu nhanh

1. Nhận API Key

API Key được tạo trong bảng điều khiển quản trị của nhà hàng của bạn.

Từng bước:

Đăng nhập vào Bảng điều khiển quản trị tại admin.meni.ge
Trong menu bên, mở ⚙️ Cài đặt → 🔑 Truy cập
Trên trang, tìm phần 🤖 MCP API Keys
Nhấn nút «Tạo khóa mới»
Nhập tên khóa (ví dụ: «Claude Desktop», «Cursor», «GPT của tôi») — điều này sẽ giúp phân biệt các khóa với nhau
Sao chép khóa ngay lập tức — nó chỉ được hiển thị một lần!

💡 Trên trang này cũng hiển thị URL server (https://api.meni.ge/mcp), bạn cũng có thể sao chép chỉ với một cú nhấp chuột.

Quản lý khóa

Bạn có thể tạo tối đa 10 khóa cho mỗi tài khoản
Mỗi khóa có thể thu hồi bất cứ lúc nào — nút «Thu hồi» bên cạnh khóa
Sau khi thu hồi, khóa sẽ ngừng hoạt động ngay lập tức
Nếu khóa bị mất — hãy thu hồi nó và tạo một khóa mới

2. Kết nối trợ lý AI

Claude Desktop / Claude Code

Tệp cấu hình claude_desktop_config.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer API_KEY_CỦA_BẠN"
      }
    }
  }
}

Cursor

Trong cài đặt Cursor → MCP Servers → Add, hoặc tệp .cursor/mcp.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer API_KEY_CỦA_BẠN"
      }
    }
  }
}

VS Code (GitHub Copilot)

Trong .vscode/mcp.json của dự án:

{
  "servers": {
    "meni": {
      "type": "http",
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer API_KEY_CỦA_BẠN"
      }
    }
  }
}

Các công cụ AI khác

Hướng dẫn chi tiết từng bước cho Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Continue, ChatGPT và các công cụ khác — trong hướng dẫn riêng:

👉 Kết nối công cụ AI với MCP

Trợ lý AI có thể làm gì?

Dành cho chủ nhà hàng (người dùng thông thường)

Lệnh	Mô tả
`whoami`	Hiển thị dữ liệu tài khoản (userId, email, vai trò)
`my_profile`	Nhận hồ sơ người dùng của bạn
`update_my_profile`	Cập nhật các trường trong hồ sơ của bạn
`my_locations`	Danh sách tất cả các địa điểm của bạn
`my_orders`	Danh sách đơn hàng của bạn
`my_images`	Danh sách hình ảnh của bạn (thực đơn, danh mục, địa điểm)

Hồ sơ người dùng

Lệnh	Mô tả
`get_user_profile`	Nhận hồ sơ người dùng theo userId
`update_user_profile`	Cập nhật các trường trong hồ sơ người dùng
`list_users`	`[ADMIN]` Danh sách tất cả người dùng
`search_user_by_email`	`[ADMIN]` Tìm người dùng theo email qua Cognito

Làm việc với địa điểm

Lệnh	Mô tả
`list_locations`	Tất cả các địa điểm của người dùng
`get_location_profile`	Hồ sơ địa điểm (tên, địa chỉ, giờ làm việc, cài đặt)
`update_location_profile`	Cập nhật cài đặt địa điểm (đồng bộ hóa tự động với CDN)
`get_location_menu`	Thực đơn đầy đủ của địa điểm với danh mục và vị trí

Làm việc với thực đơn

Lệnh	Mô tả
`list_menu_items`	Tất cả các vị trí trong thực đơn (với categoryId — dữ liệu đầy đủ, không có — cặp item/category ID)
`get_menu_item`	Nhận vị trí với dữ liệu đầy đủ (bao gồm bản dịch, tùy chọn, bổ sung)
`update_menu_item`	Cập nhật vị trí trong thực đơn (giá, mô tả, trạng thái, thẻ, tùy chọn, bổ sung)
`create_menu_item`	Tạo vị trí mới trong thực đơn trong danh mục
`create_menu_category`	Tạo danh mục mới trong thực đơn
`update_menu_category`	Cập nhật danh mục (tên, bản dịch, trạng thái, thứ tự sắp xếp)
`move_menu_item`	Di chuyển vị trí từ danh mục này sang danh mục khác
`merge_categories`	Hợp nhất hai danh mục (tất cả các vị trí được di chuyển, danh mục gốc bị xóa)
`delete_menu_category`	Xóa danh mục (với `force: true` — cùng với tất cả các vị trí)

Đơn hàng

Lệnh	Mô tả
`list_orders`	Danh sách đơn hàng (theo userId hoặc domain)
`get_order`	Chi tiết đơn hàng cụ thể

Domain

Lệnh	Mô tả
`check_domain_availability`	Kiểm tra tính khả dụng của tên miền
`set_location_domain`	Thay đổi tên miền của địa điểm (cập nhật CDN và ánh xạ)
`resolve_domain`	Tìm userId và locationId theo domain
`list_domains`	`[ADMIN]` Danh sách tất cả các domain đã đăng ký

CDN (dữ liệu đã công bố)

Lệnh	Mô tả
`get_cdn_profile`	Hồ sơ địa điểm đã công bố (trên CDN)
`get_cdn_menu`	Thực đơn đã công bố bằng ngôn ngữ chỉ định
`list_cdn_files`	Tất cả các tệp đã công bố của domain
`invalidate_cdn_cache`	`[ADMIN]` Xóa bộ nhớ đệm CloudFront CDN

Hình ảnh

Lệnh	Mô tả
`list_user_images`	Tất cả hình ảnh của người dùng
`get_image_upload_url`	Nhận presigned URL để tải hình ảnh lên S3 (JPEG/PNG/WebP)
`delete_image`	Xóa hình ảnh (người dùng — chỉ của mình)

Truy cập cấp thấp vào S3

Lệnh	Mô tả
`s3_read`	Đọc tệp từ S3 (người dùng — chỉ của mình)
`s3_write`	`[ADMIN]` Ghi dữ liệu JSON vào S3
`s3_list`	Danh sách tệp trong S3 (người dùng — chỉ tiền tố của mình)
`s3_delete`	`[ADMIN]` Xóa đối tượng khỏi S3

Cognito

Lệnh	Mô tả
`cognito_list_users`	`[ADMIN]` Danh sách người dùng từ Cognito User Pool
`cognito_get_user`	`[ADMIN]` Thông tin chi tiết về người dùng Cognito

Thống kê

Lệnh	Mô tả
`get_system_stats`	`[ADMIN]` Thống kê toàn hệ thống

Xác thực

Server hỗ trợ ba phương thức ủy quyền:

1. API Key (khuyến nghị cho trợ lý AI)

Authorization: Bearer api_key_64_ký_tự_của_bạn

Khóa được tạo trong bảng điều khiển quản trị. Liên kết với tài khoản của bạn — AI chỉ thấy dữ liệu của bạn.

2. Cognito JWT Token

Để tích hợp lập trình, bạn có thể nhận token qua đăng nhập:

# Nhận token
curl -X POST https://api.meni.ge/mcp/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "email_của_bạn@email.com", "password": "mật_khẩu_của_bạn"}'

# Phản hồi chứa idToken — sử dụng nó:
Authorization: Bearer eyJraWQ...

Token có hiệu lực trong 1 giờ, sau đó cần đăng nhập lại.

3. Admin API Key (chỉ dành cho quản trị viên)

Authorization: Bearer admin_key

Khóa quản trị viên cung cấp quyền truy cập đầy đủ vào tất cả dữ liệu của tất cả người dùng.

Bảo mật

Mỗi API Key được liên kết với một tài khoản cụ thể
Người dùng thông thường chỉ thấy dữ liệu của mình
Khóa có thể thu hồi bất cứ lúc nào trong bảng điều khiển quản trị
Tối đa 10 khóa cho mỗi tài khoản
Tất cả các yêu cầu đều thông qua HTTPS
Các lệnh được đánh dấu [ADMIN] không khả dụng cho người dùng thông thường

Ví dụ sử dụng

Yêu cầu AI cập nhật giá món ăn

«Cập nhật giá món «Khachapuri» trong thực đơn của tôi — làm 15 lari thay vì 12»

AI sẽ gọi my_locations → get_location_menu → update_menu_item.

Thêm vị trí mới vào thực đơn

«Thêm món mới «Churchkhela» vào danh mục «Tráng miệng» với giá 8 lari»

AI sẽ gọi my_locations → get_location_menu → create_menu_item.

Tạo danh mục mới

«Tạo danh mục «Đồ uống» với bản dịch sang tiếng Gruzia và tiếng Anh»

AI sẽ gọi create_menu_category với nameTranslations.

Di chuyển món ăn giữa các danh mục

«Di chuyển «Limonade» từ «Đồ uống lạnh» sang «Không cồn»»

AI sẽ gọi move_menu_item với chỉ định danh mục gốc và mục tiêu.

Xem đơn hàng hôm nay

«Hiển thị đơn hàng của tôi hôm nay»

AI sẽ gọi my_orders và lọc theo ngày.

Kiểm tra thực đơn đã công bố

«Thực đơn của tôi trông như thế nào bằng tiếng Nga cho khách truy cập?»

AI sẽ gọi resolve_domain → get_cdn_menu với ngôn ngữ ru.

Thay đổi domain nhà hàng

«Kiểm tra xem domain my-restaurant có khả dụng không, nếu có — thiết lập nó»

AI sẽ gọi check_domain_availability → set_location_domain.

Tải ảnh món ăn

«Cho tôi liên kết để tải ảnh cho món X»

AI sẽ gọi get_image_upload_url và trả về presigned URL để tải lên.

API Endpoints

Phương thức	URL	Mô tả
`GET`	`https://api.meni.ge/mcp`	Thông tin về server + danh sách công cụ
`POST`	`https://api.meni.ge/mcp`	MCP JSON-RPC (giao thức chính)
`GET`	`https://api.meni.ge/mcp/health`	Kiểm tra hoạt động
`POST`	`https://api.meni.ge/mcp/auth/login`	Đăng nhập → JWT tokens
`GET`	`https://api.meni.ge/mcp/api/keys`	Danh sách API Key của bạn
`POST`	`https://api.meni.ge/mcp/api/keys`	Tạo API Key mới
`DELETE`	`https://api.meni.ge/mcp/api/keys/{id}`	Thu hồi API Key

Quản lý khóa

Xem khóa

Trong bảng điều khiển quản trị → Cài đặt → Truy cập → MCP API Keys. Hoặc qua API:

curl https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

Tạo khóa

curl -X POST https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop"}'

Phản hồi chứa trường key — đây là khóa của bạn. Lưu trữ nó!

Thu hồi khóa

curl -X DELETE https://api.meni.ge/mcp/api/keys/mk_abc123 \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

⚠️ Tạo và thu hồi khóa yêu cầu Cognito JWT Token (không phải API Key). Sử dụng bảng điều khiển quản trị — điều này dễ dàng hơn.

Khắc phục sự cố

Vấn đề	Giải pháp
`401 Unauthorized`	Kiểm tra API Key. Nếu đã thu hồi — tạo một cái mới
`403 user identity required`	Sử dụng Cognito JWT để quản lý khóa
`🔒 admin access required`	Lệnh chỉ khả dụng cho quản trị viên
`🔒 access denied`	Bạn đang cố gắng truy cập dữ liệu của người dùng khác
Khóa không hoạt động	Kiểm tra xem khóa có bị thu hồi không, và định dạng: `Bearer <khóa>`