餐厅管理系统

Restaurante MCP

Proyecto de gestión de un restaurante implementado con arquitectura de microservicios básica, utilizando Java con Spring Boot para el backend y MySQL como base de datos, todo orquestado con Docker Compose.

Tecnologías del Stack

Dependencias del Backend

El backend utiliza las siguientes dependencias principales organizadas por categoría:

Framework Principal

Base de Datos

MCP (Model Context Protocol)

Testing

Herramientas de Build

Estructura del Proyecto

El proyecto está organizado en módulos que separan las responsabilidades:

• backend/: Contiene el código fuente de la aplicación Spring Boot.
• db/: Contiene los scripts SQL para la inicialización de la base de datos (e.g., init.sql).
• infra/: Contiene los archivos de configuración de infraestructura (.env.dev.example, compose.dev.yml).

Arquitectura del sistema

El siguiente diagrama ilustra la arquitectura de la solución, mostrando cómo Docker Compose orquesta los servicios clave y el flujo de datos.

El Usuario/Host accede a la API REST del Backend a través del puerto expuesto (BACKEND_PORT). Una vez dentro de la orquestación, el Backend se conecta al Servicio DB mediante el protocolo JDBC, completando el ciclo de petición y respuesta.

graph TD
    A[Usuario/Host]
    
    subgraph DOCKER_COMPOSE[Orquestación Docker Compose]
        style DOCKER_COMPOSE stroke:#00BCD4,stroke-width:2px
        C("**servicio backend** <br> Spring Boot <br> <small>puerto 8080</small>")
        D("**servicio db** <br> MySQL 9 <br> <small>puerto 3306</small>")
        
        C -->|"[JDBC]"| D
    end

    A -->|"[JSON/HTTP] <br> <small> puerto BACKEND_PORT </small>"| C

Variables de entorno

El archivo infra/.env.dev.example define las siguientes variables utilizadas por Docker Compose y la aplicación backend. Deben ser copiadas y configuradas en infra/.env.dev antes de la ejecución.

Ejecutar el entorno de desarrollo

1. Copiar y Configurar Variables de Entorno: Copiar el archivo de ejemplo para crear la configuración local de desarrollo.

   复制

   cp infra/.env.dev.example infra/.env.dev
   

   Editar el archivo infra/.env.dev para ajustar las variables de entorno, como puertos y credenciales de la base de datos, si es necesario.

2. Levantar Servicios: Para construir y levantar ambos servicios (db y backend) en modo detached (segundo plano), utilizar el siguiente comando:

   复制

   docker compose -f infra/compose.dev.yml --env-file infra/.env.dev up --build -d
   

3. Verificar Servicios: Para verificar que los servicios están corriendo correctamente, utilizar:

   复制

   docker compose -f infra/compose.dev.yml --env-file infra/.env.dev ps
   

4. Acceder a la API REST: La API REST del backend estará disponible en http://localhost:<BACKEND_PORT>, donde <BACKEND_PORT> es el puerto configurado en el archivo .env.dev.

5. Detener Servicios: Para detener y eliminar los contenedores (manteniendo los volúmenes), utilizar:

   复制

   docker compose -f infra/compose.dev.yml --env-file infra/.env.dev down
   

   Para detener y eliminar los contenedores, redes y volúmenes creados por Docker Compose, utilizar:

   复制

   docker compose -f infra/compose.dev.yml --env-file infra/.env.dev down -v
   

Base de datos

El servicio de base de datos se inicializa automáticamente en el primer arranque a partir del script db/init.sql.

Diagrama Entidad-Relación (ERD)

erDiagram

    PLATOS {
        BIGINT plato_id PK
        VARCHAR tipo
        VARCHAR nombre
        TEXT descripcion
    }

    MENUS {
        BIGINT menu_id PK
        TEXT descripcion
        DATE fecha
    }

    PLATOS_MENU {
        BIGINT menu_id PK, FK
        BIGINT plato_id PK, FK
        DECIMAL precio "DECIMAL(10,2)"
    }

    VENTAS {
        BIGINT venta_id PK
        DATE fecha
    }

    VENTAS_MENU {
        BIGINT menu_id PK, FK
        BIGINT venta_id PK, FK
        INT cantidad
    }

    %% Relaciones
    PLATOS ||--o{ PLATOS_MENU : "contiene"
    MENUS ||--o{ PLATOS_MENU : "incluye"

    MENUS ||--o{ VENTAS_MENU : "se vende en"
    VENTAS ||--o{ VENTAS_MENU : "registra"

Modo MCP con Claude Desktop

Este proyecto implementa un servidor MCP (Model Context Protocol) que permite a Claude Desktop interactuar directamente con la base de datos del restaurante a través de herramientas especializadas.

Herramientas MCP disponibles

Instalación de Claude Desktop en Arch Linux

Opción 1: Usando AUR

# Instalar claude-desktop-native (más estable)
yay -S claude-desktop-native

# O alternativamente
yay -S claude-desktop-bin

Compilación standalone

Para usar el servidor MCP, necesitas compilar un JAR standalone:

# Navegar al directorio del backend
cd backend

# Compilar el JAR standalone
./gradlew bootJar

# Verificar que se generó el archivo
ls -la build/libs/backend-1.0-SNAPSHOT.jar

Configuración claude_desktop_config.json

1. Crear el directorio de configuración de Claude Desktop:

mkdir -p ~/.config/Claude

2. Crear el archivo de configuración:

nano ~/.config/Claude/claude_desktop_config.json

3. Contenido del archivo de configuración:

Remplaza /ruta/absoluta/a/tu/proyecto con la ruta real del proyecto en tu sistema y ajusta las variables de entorno según tu configuración.

{
  "mcpServers": {
    "restaurant-mcp": {
      "command": "java",
      "args": [
        "-Dspring.profiles.active=mcp",
        "-jar",
        "/ruta/absoluta/a/tu/proyecto/backend/build/libs/backend-1.0-SNAPSHOT.jar"
      ],
      "env": {
        "SPRING_DATASOURCE_URL": "jdbc:mysql://localhost:21911/restaurante",
        "SPRING_DATASOURCE_USERNAME": "restaurante_user",
        "SPRING_DATASOURCE_PASSWORD": "restaurante_pass",
        "SPRING_JPA_HIBERNATE_DDL_AUTO": "update",
        "SPRING_JPA_SHOW_SQL": "false"
      }
    }
  }
}

4. Ajustar la ruta del JAR en la configuración JSON para que coincida con la ubicación real de tu proyecto.

5. Reiniciar Claude Desktop para cargar la nueva configuración.

Uso con Claude Desktop

Una vez configurado, puedes usar comandos naturales en Claude Desktop como:

• "Lista todos los platos del restaurante"
• "Crea un nuevo plato llamado 'Paella Valenciana' de tipo 'Plato Principal' con descripción 'Arroz con mariscos y pollo'"
• "Busca el plato con ID 2"
• "Actualiza el plato con ID 3 cambiando su nombre a 'Tiramisú Clásico'"
• "Elimina el plato con ID 1"

Profiles de Spring Boot

El proyecto utiliza profiles para separar las configuraciones:

• Profile por defecto (application.properties): Modo servlet web con logs normales
• Profile mcp (application-mcp.properties): Modo STDIO sin servidor web, logs silenciados para comunicación JSON limpia con Claude Desktop

Solución de problemas

1. Verificar que MySQL esté corriendo:

   复制

   docker ps | grep restaurante_db_dev
   

2. Verificar logs de Claude Desktop:

   复制

   claude-desktop-native