Demo-MCPServer by JuanLadinoMoreno - MCP Server

FastFoodMCP 🚀

Un servidor MCP (Model Context Protocol) enterprise-ready para gestionar datos de un sistema de comida rápida con autenticación OAuth 2.1 segura mediante Scalekit.

📋 Descripción

FastFoodMCP es un servidor que implementa el protocolo MCP para conectar Claude y otras herramientas de IA con una API REST de gestión de comida rápida. Incluye autenticación OAuth integrada, validación de scopes y herramientas especializadas para análisis de ventas, gestión de usuarios y productos.

Características principales:

✅ OAuth 2.1 con Scalekit - Autenticación segura y validación de tokens
✅ 8+ Tools - Funciones especializadas para consultas y análisis
✅ 2 Prompts - Reportes ejecutivos y análisis de usuarios
✅ TypeScript - Código tipado y seguro
✅ Validación de Scopes - Control granular de permisos por herramienta
✅ Manejo de errores robusto - Respuestas JSON-RPC 2.0 compliant
✅ Logging avanzado - Winston para auditoría y debugging

🏗️ Arquitectura

FastFoodMCP (MCP Server)
    ├── OAuth 2.1 (Scalekit)
    │   └── Validación de tokens y scopes
    │
    ├── Tools (Herramientas)
    │   ├── Users (get_users, create_user)
    │   ├── Products (get_products)
    │   ├── Branches (get_branches)
    │   ├── Clients (get_clients)
    │   ├── Orders (get_orders, get_orders_summary)
    │   └── Sales (get_tickets, get_tickets_summary, reportes por año)
    │
    ├── Prompts (Plantillas inteligentes)
    │   ├── Monthly Sales Report (Reporte ejecutivo)
    │   └── Users Report (Análisis de usuarios)
    │
    └── Backend API REST
        └── Validación con JWT + Scalekit OAuth

🛠️ Tech Stack

Node.js + Express - Servidor HTTP
TypeScript - Type-safe
MCP SDK - Protocolo Model Context Protocol
Scalekit SDK - Autenticación OAuth
Zod - Validación de schemas
Winston - Logging profesional
Axios - Cliente HTTP para la API REST

🚀 Inicio Rápido

Prerrequisitos

Node.js 18+
npm o yarn
Cuenta en Scalekit
API REST funcionando (backend)

Instalación

Clona el repositorio

git clone https://github.com/tuusuario/FastFoodMCP.git
cd FastFoodMCP

Instala dependencias

npm install

Configura variables de entorno

cp .env.example .env

Edita .env con tus credenciales de Scalekit:

SK_ENV_URL=https://sta.scalekit.dev
SK_CLIENT_ID=tu_client_id
SK_CLIENT_SECRET=tu_client_secret
MCP_SERVER_ID=tu_mcp_server_id
BASE_URL=http://tu-ip-local
PORT=3003
BASE_URL_API=http://localhost:8080/api

Compila TypeScript

npm run build

Inicia el servidor

npm start

El servidor estará disponible en: http://localhost:3003

📡 Autenticación OAuth

Este servidor requiere autenticación OAuth 2.1 con Scalekit.

Flujo de Autenticación

Cliente intenta conectar al MCP server
Servidor responde con 401 + header OAuth
Cliente abre navegador en Scalekit para login
Usuario se autentica
Token se envía en header Authorization: Bearer <token>
Servidor valida token y scopes
Herramientas se ejecutan con permisos validados

Scopes Soportados

usr:read - Lectura de usuarios, productos, órdenes
usr:write - Crear nuevos usuarios

Integración con Claude Desktop

Para usar con Claude Desktop:

Instala Claude Desktop
Abre ~/.claude/claude_desktop_config.json (o C:\Users\[tu-usuario]\AppData\Roaming\Claude\claude_desktop_config.json en Windows)
Agrega tu MCP server:

{
  "mcpServers": {
    "fastfood": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3003/", "--allow-http"]
    }
  }
}

Abre Claude Desktop
Se abrirá automáticamente la pantalla de login de Scalekit
Después de autenticarte, podrás usar todas las tools

🔧 Tools Disponibles

Users

get_users - Lista todos los usuarios con filtros opcionales (nombre, email)
create_user - Crea un nuevo usuario en el sistema

Productos

get_products - Obtiene todos los productos disponibles

Ramas/Sucursales

get_branches - Lista todas las sucursales

Clientes

get_clients - Lista clientes con filtros

Órdenes

get_orders - Consulta órdenes con filtros avanzados (fecha, sucursal, estado)
get_orders_summary - Resumen agregado de órdenes por sucursal, usuario, cliente

Ventas/Tickets

get_tickets - Lista de ventas completadas con múltiples filtros
get_tickets_summary - Análisis agregado con groupBy para comparativas rápidas
get_Branch_Sales_Report_By_Year - Reporte mensual de ventas por año
get_Branch_Sales_Report_By_Year_Type - Ventas por tipo de producto y mes
get_Top_Seller_Products - Top 10 productos más vendidos

📊 Prompts Disponibles

Monthly Sales Report

Genera un reporte ejecutivo de ventas con:

Métricas clave (ingresos, tickets, ticket promedio)
Top 3-5 productos
Análisis comparativo vs mes anterior
Insights y recomendaciones
Presentación en dashboard gráfico

Users Report

Análisis comprehensivo de usuarios con filtros personalizados

🔐 Seguridad

✅ Validación de tokens OAuth en cada request
✅ Validación de scopes por herramienta
✅ Protección de endpoints públicos (.well-known)
✅ Manejo seguro de secretos via .env
✅ Validación de nbf (not before) claim
✅ Control de CORS configurado
✅ Logging de todas las autenticaciones fallidas

📦 Estructura del Proyecto

src/
├── config/          # Configuración (variables de entorno)
├── lib/
│   ├── auth.ts      # Handler OAuth
│   ├── middleware.ts # Middleware de autenticación
│   ├── logger.ts    # Configuración de logs
│   └── transport.ts # Setup de transporte MCP
├── services/        # Servicios que llaman a la API REST
├── tools/           # Definición de herramientas MCP
│   ├── users/
│   ├── products/
│   ├── branches/
│   ├── clients/
│   ├── orders/
│   └── sales/
├── prompts/         # Definición de prompts
│   └── sales/
└── server.ts        # Punto de entrada

🎯 Casos de Uso

Análisis de ventas en tiempo real - Consulta tendencias y top productos
Reportes ejecutivos - Genera reportes automáticos para el CEO
Gestión de usuarios - Consulta y crea usuarios en el sistema
Auditoría de órdenes - Revisa historial de compras por período
Análisis comparativo - Compara sucursales, usuarios y períodos

📹 Demo

Puedes ver una demostración completa del servidor funcionando en acción aquí:

[Link al video demo] (Agregará cuando tengas el video publicado)

El video muestra:

Setup inicial en VSCode
Flujo OAuth con Scalekit
Ejecución de las 8+ tools
Generación de reportes ejecutivos
Análisis de datos en tiempo real

📖 API REST Backend

Este MCP server se conecta a una API REST que implementa:

Autenticación dual: JWT + Cookie para web, Scalekit para MCP
Endpoints: Users, Products, Branches, Clients, Orders, Tickets
Validación de Scalekit en middleware separado
Controllers y Services compartidos entre web y MCP

[Link a documentación de API REST]

🧪 Testing

Tests aún en desarrollo.

📝 Logs

Los logs se guardan en logs/ con niveles: info, warn, error

tail -f logs/app.log

🐛 Troubleshooting

"Missing Bearer token"

Asegúrate de haber autenticado con Scalekit
Limpia caché del navegador
Reinicia Claude Desktop

"Token validation failed"

Verifica que tu SK_CLIENT_SECRET es correcto
Revisa que tu MCP_SERVER_ID coincide en Scalekit
Comprueba que la URL en PROTECTED_RESOURCE_METADATA es correcta

"No response from API server"

Verifica que tu API REST está corriendo en BASE_URL_API
Comprueba la URL en .env

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

Fork el proyecto
Crea una rama (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

👤 Autor

Juan Simón Ladino Moreno

GitHub: https://github.com/JuanLadinoMoreno
LinkedIn: https://www.linkedin.com/in/juansim%C3%B3nladino/

🙏 Agradecimientos

Scalekit por la plataforma OAuth
Anthropic por el protocolo MCP
Claude por la integración

Creado con ❤️ por Juan Ladino