MCP Servidor meni.ge — Guía para la integración de AI / GPT

Este documento está destinado a asistentes AI, bots GPT e integraciones automáticas. Contiene detalles precisos del protocolo, esquemas de herramientas y flujo de autenticación.

Información del servidor

Propiedad	Valor
Nombre del servidor	meni-user-data-mcp
Protocolo	MCP 2024-11-05 (Streamable HTTP)
Transporte	HTTP POST (stateless)
URL base	`https://api.meni.ge/mcp`
Content-Type	`application/json`
Formato	JSON-RPC 2.0

Autenticación

Todas las llamadas a herramientas requieren el encabezado Authorization.

Opción 1: Clave de API MCP de usuario (recomendado)

Authorization: Bearer mk_XXXXXXXXXXXX...  (64 caracteres hexadecimales)

Vinculado a un usuario específico. El bot solo ve los datos de este usuario.

Opción 2: Token JWT de Cognito

Authorization: Bearer eyJraWQi...  (JWT id_token)

Se obtiene a través de POST /auth/login. Expira en 1 hora.

Opción 3: Clave de API de administrador

Authorization: Bearer <admin_api_key>

Acceso completo a todos los datos. Solo para administradores.

Obtención del token JWT

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

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

Respuesta:

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

Protocolo MCP

Inicialización

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

Lista de herramientas

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

Llamada a herramienta

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "nombre_de_la_herramienta",
    "arguments": { ... }
  }
}

Respuesta (éxito): result.content[0].text — Cadena JSON con datos.
Respuesta (error): result.isError: true, result.content[0].text — Texto del error.

Endpoints

Método	Ruta	Autorización	Descripción
`GET`	`/`	No	Información del servidor + lista de herramientas
`POST`	`/`	Sí	MCP JSON-RPC
`GET`	`/health`	No	Comprobación → `{"status":"ok"}`
`POST`	`/auth/login`	No	Inicio de sesión → Tokens JWT
`GET`	`/api/keys`	Solo JWT	Lista de claves API
`POST`	`/api/keys`	Solo JWT	Crear clave API
`DELETE`	`/api/keys/{keyId}`	Solo JWT	Revocar clave API

Todas las rutas son relativas a https://api.meni.ge/mcp.

Guía completa de herramientas

Niveles de acceso

USER — Disponible para todos los usuarios autorizados (datos de su propia cuenta)
ADMIN — Solo administradores (acceso completo)

Autoservicio

Herramienta	Acceso	Argumentos
`whoami`	USER	ninguno
`my_profile`	USER	ninguno
`update_my_profile`	USER	`fields` (object, obligatorio)
`my_locations`	USER	ninguno
`my_orders`	USER	`limit` (int, opcional)
`my_images`	USER	`type` (enum: all, menu-photos, category-photos, locations, opcional)

Perfiles de usuarios

Herramienta	Acceso	Argumentos
`list_users`	ADMIN	`limit` (int, opcional)
`get_user_profile`	USER/ADMIN	`userId` (string, obligatorio)
`update_user_profile`	ADMIN	`userId` (string, obligatorio), `fields` (object, obligatorio)
`search_user_by_email`	ADMIN	`email` (string, obligatorio)

Localizaciones

Herramienta	Acceso	Argumentos
`list_locations`	USER/ADMIN	`userId` (string, obligatorio)
`get_location_profile`	USER/ADMIN	`locationId` (string, obligatorio), `userId` (string, opcional — auto-detección para usuarios normales)
`update_location_profile`	USER/ADMIN	`locationId` (string, obligatorio), `fields` (object, obligatorio), `userId` (string, opcional)
`get_location_menu`	USER/ADMIN	`locationId` (string, obligatorio), `language` (string, opcional), `userId` (string, opcional)

update_location_profile — campos actualizables: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. Se sincroniza automáticamente con CDN. Para cambiar el dominio, use set_location_domain.

Menú

Herramienta	Acceso	Argumentos
`list_menu_items`	USER/ADMIN	`categoryId` (string, opcional — para datos completos), `userId` (string, opcional)
`get_menu_item`	USER/ADMIN	`itemId` (string, obligatorio), `categoryId` (string, opcional — auto-búsqueda), `userId` (string, opcional)
`update_menu_item`	USER/ADMIN	`itemId` (string, obligatorio), `fields` (object, obligatorio), `categoryId` (string, opcional), `userId` (string, opcional)
`create_menu_item`	USER/ADMIN	`locationId`, `categoryId`, `itemId`, `name` (string, obligatorio), `price` (number, obligatorio), `nameTranslations` (object, opcional), `description` (string, opcional), `status` (enum, opcional), `sortOrder` (number, opcional), `userId` (string, opcional)
`create_menu_category`	USER/ADMIN	`locationId`, `categoryId`, `name` (string, obligatorio), `nameTranslations` (object, opcional), `status` (enum, opcional), `sortOrder` (number, opcional), `userId` (string, opcional)
`update_menu_category`	USER/ADMIN	`locationId`, `categoryId` (string, obligatorio), `name` (string, opcional), `nameTranslations` (object, opcional), `status` (enum, opcional), `sortOrder` (number, opcional), `userId` (string, opcional)
`move_menu_item`	USER/ADMIN	`locationId`, `itemId`, `fromCategoryId`, `toCategoryId` (string, obligatorio), `userId` (string, opcional)
`merge_categories`	USER/ADMIN	`locationId`, `sourceCategoryId`, `targetCategoryId` (string, obligatorio), `keepSourceName` (bool, opcional), `userId` (string, opcional)
`delete_menu_category`	USER/ADMIN	`locationId`, `categoryId` (string, obligatorio), `force` (bool, opcional — eliminar con posiciones), `userId` (string, opcional)

update_menu_item — campos actualizables: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. Se sincroniza automáticamente con CDN.

Pedidos

Herramienta	Acceso	Argumentos
`list_orders`	USER/ADMIN	`userId` (opcional), `domain` (opcional), `limit` (int, opcional)
`get_order`	USER/ADMIN	`orderId` (string, obligatorio), `domain` (string, opcional), `locationId` (string, opcional)

Dominios

Herramienta	Acceso	Argumentos
`check_domain_availability`	USER	`domainName` (string, obligatorio), `currentDomainName` (string, opcional)
`set_location_domain`	USER/ADMIN	`locationId` (string, obligatorio), `domainName` (string, obligatorio)
`resolve_domain`	USER	`domain` (string, obligatorio)
`list_domains`	ADMIN	`prefix` (string, opcional)

CDN

Herramienta	Acceso	Argumentos
`get_cdn_profile`	USER	`domain` (string, obligatorio)
`get_cdn_menu`	USER	`domain` (string, obligatorio), `language` (string, obligatorio)
`list_cdn_files`	USER	`domain` (string, obligatorio)
`invalidate_cdn_cache`	ADMIN	`paths` (string[], obligatorio)

Imágenes

Herramienta	Acceso	Argumentos
`list_user_images`	USER/ADMIN	`userId` (string, obligatorio), `type` (enum, opcional)
`get_image_upload_url`	USER	`type` (enum: menu-photos, category-photos, locations, obligatorio), `itemId` (string, opcional), `locationId` (string, opcional), `filename` (string, opcional), `contentType` (enum, opcional)
`delete_image`	USER/ADMIN	`key` (string, obligatorio — clave completa de S3 en i.meni.ge)

get_image_upload_url — devuelve una URL presignada (15 min). Después de la carga, el pipeline genera automáticamente miniaturas y se sincroniza con CDN.

S3 (almacenamiento)

Herramienta	Acceso	Argumentos
`s3_read`	USER/ADMIN	`bucket` (enum), `key` (string) — obligatorio
`s3_write`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (string), `data` (object) — obligatorio
`s3_list`	USER/ADMIN	`bucket` (enum), `prefix` (string) — obligatorio, `limit` (int, opcional)
`s3_delete`	ADMIN	`bucket` (enum: data.meni, cdn.meni.ge, o.meni.ge), `key` (string) — obligatorio

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

Cognito

Herramienta	Acceso	Argumentos
`cognito_list_users`	ADMIN	`filter` (string, opcional), `limit` (int, opcional)
`cognito_get_user`	ADMIN	`username` (string, obligatorio)

Sistema

Herramienta	Acceso	Argumentos
`get_system_stats`	ADMIN	ninguno

Control de acceso

Usuarios normales — solo sus propios datos (por userId)
Acceso a S3 limitado por el prefijo users/{userId}/
Para herramientas de localizaciones/menú userId se auto-detecta para usuarios normales (solo los administradores lo especifican)
Solo para administradores: 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
Gestión de claves (/api/keys) requiere JWT de Cognito

Códigos de error

HTTP	Valor
`200`	Éxito (verifique `result.isError` para errores de herramientas)
`400`	JSON no válido o método faltante
`401`	Autenticación faltante o no válida
`405`	Método HTTP incorrecto

Error de herramienta	Valor
`🔒 admin access required`	Se requiere rol de administrador
`🔒 access denied`	Intento de acceso a datos ajenos
`missing required argument: <name>`	Parámetro obligatorio no proporcionado
`unknown tool: <name>`	Herramienta desconocida

Ejemplo de sesió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\"}"}]}}

Configuración del cliente

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