MCP Server - Tienda de Suplementos Deportivos
Servidor MCP (Model Context Protocol) que conecta un LLM con una base de datos PostgreSQL de e-commerce. Permite a agentes de IA buscar productos, consultar pedidos, gestionar clientes y crear órdenes a través de herramientas estructuradas.
┌──────────────┐ Streamable HTTP ┌──────────────┐ SQL ┌────────────┐
│ LLM Client │◄─────────────────────►│ MCP Server │◄───────────────►│ PostgreSQL │
│ (Claude, │ JSON-RPC 2.0 │ :9333/mcp │ │ :7667 │
│ GPT, etc.) │ └──────────────┘ └────────────┘
└──────────────┘Inicio Rápido
Requisitos previos
1. Clonar e instalar
git clone https://github.com/sebastiancastillorock/mcpserverecommerce.git
cd mcpserverecommerce
npm install2. Configurar variables de entorno
cp .env.example .envEl archivo .env contiene:
MCP_HOST=0.0.0.0
MCP_PORT=9333
DATABASE_URL=postgresql://mcp_readonly:mcp_readonly_2024@localhost:7667/suplementos_db
DATABASE_ORDERS_URL=postgresql://mcp_orders:mcp_orders_2024@localhost:7667/suplementos_db3. Levantar la base de datos
docker compose up -dEsto crea la base de datos PostgreSQL con el esquema y datos de ejemplo automáticamente.
4. Iniciar el servidor
# Desarrollo (hot reload)
npm run dev
# Producción
npm run build && npm startEl servidor estará disponible en http://localhost:9333/mcp.
---
Conectar tu propia base de datos
Si quieres usar este servidor con tu propia base de datos PostgreSQL (en lugar de la incluida con Docker), sigue estos pasos:
Opción A: Apuntar a una base de datos existente
Solo necesitas modificar las variables de entorno en .env:
# Conexión de solo lectura (consultas)
DATABASE_URL=postgresql://USUARIO:PASSWORD@HOST:PUERTO/NOMBRE_DB
# Conexión de escritura (crear pedidos y clientes)
DATABASE_ORDERS_URL=postgresql://USUARIO_ESCRITURA:PASSWORD@HOST:PUERTO/NOMBRE_DBEjemplos:
# PostgreSQL local
DATABASE_URL=postgresql://mi_usuario:mi_password@localhost:5432/mi_tienda
# Servidor remoto
DATABASE_URL=postgresql://admin:secreto@db.miservidor.com:5432/ecommerce
# Servicios cloud (Supabase, Neon, Railway, etc.)
DATABASE_URL=postgresql://user:pass@db.xxxx.supabase.co:5432/postgresOpción B: Crear el esquema en tu base de datos
Si tu base de datos está vacía, ejecuta los scripts SQL incluidos para crear las tablas necesarias:
# Conectar a tu PostgreSQL y ejecutar el esquema
psql -h HOST -U USUARIO -d NOMBRE_DB -f init-db/01-schema.sql
# (Opcional) Cargar datos de ejemplo
psql -h HOST -U USUARIO -d NOMBRE_DB -f init-db/02-seed-data.sqlOpción C: Adaptar el esquema a tu base de datos existente
Si ya tienes una base de datos con estructura diferente, necesitas modificar las queries SQL en src/index.ts. El servidor espera estas tablas:
-- Tabla de productos (catálogo)
productos (id, nombre, descripcion, precio, stock, categoria, ingredientes, marca)
-- Tabla de clientes
clientes (id, nombre, email, telefono, direccion)
-- Tabla de pedidos
pedidos (id, numero_pedido, cliente_id, estado, fecha_pedido, total, direccion_envio, notas)
-- Detalle de cada pedido
detalle_pedidos (id, pedido_id, producto_id, cantidad, precio_unitario)Si tus tablas tienen otros nombres o columnas, busca las queries SELECT, INSERT y UPDATE en src/index.ts y src/db.ts y adáptalas a tu esquema.
Usuarios de base de datos recomendados
Para mayor seguridad, se recomienda crear dos usuarios con permisos separados:
-- Usuario de solo lectura (para consultas)
CREATE USER mcp_readonly WITH PASSWORD 'tu_password_seguro';
GRANT CONNECT ON DATABASE tu_db TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
-- Usuario de escritura limitada (para crear pedidos)
CREATE USER mcp_orders WITH PASSWORD 'otro_password_seguro';
GRANT CONNECT ON DATABASE tu_db TO mcp_orders;
GRANT USAGE ON SCHEMA public TO mcp_orders;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_orders;
GRANT INSERT ON pedidos, detalle_pedidos, clientes TO mcp_orders;
GRANT UPDATE (stock) ON productos TO mcp_orders;
GRANT USAGE, SELECT ON SEQUENCE pedidos_id_seq, detalle_pedidos_id_seq, clientes_id_seq TO mcp_orders;Si prefieres usar un solo usuario, puedes poner la misma URL en ambas variables (
DATABASE_URLyDATABASE_ORDERS_URL).
---
Conectar un LLM al servidor
Configuración del cliente MCP
Agrega esta configuración en tu cliente MCP (Claude Desktop, Cursor, etc.):
{
"mcpServers": {
"suplementos": {
"url": "http://localhost:9333/mcp",
"transport": "streamable-http"
}
}
}Si el servidor está en una máquina remota, reemplaza localhost con la IP o dominio del servidor.
System prompts
El repositorio incluye prompts de sistema optimizados para agentes:
system-prompt.md- Para agentes que usan las herramientas MCPsystem-prompt-sql.md- Para agentes con acceso SQL directo
---
Herramientas MCP disponibles
| Herramienta | Descripción | Permisos | |-------------|-------------|----------| | buscar_productos | Buscar productos por nombre, categoría o ingredientes | Lectura | | obtener_producto | Detalle completo de un producto por ID o nombre | Lectura | | verificar_disponibilidad | Consultar stock de uno o varios productos | Lectura | | consultar_pedido | Estado de un pedido (requiere email de verificación) | Lectura | | historial_cliente | Pedidos anteriores de un cliente por email | Lectura | | registrar_cliente | Crear un nuevo cliente en el sistema | Escritura | | crear_pedido | Crear un pedido con validación de stock | Escritura |
Consulta MCP-TOOLS.md para la documentación detallada de cada herramienta con ejemplos de request/response.
---
Endpoints HTTP
| Método | Ruta | Descripción | |--------|------|-------------| | POST | /mcp | Comandos MCP (JSON-RPC 2.0) | | GET | /mcp | Stream SSE para notificaciones | | DELETE | /mcp | Cerrar sesión MCP | | GET | /health | Health check |
---
Seguridad
El servidor implementa múltiples capas de seguridad:
- Pools separados: Usuario de solo lectura para consultas, usuario limitado para escritura
- Anti-DoS: Límite máximo de 50 resultados por consulta
- Anti-IDOR: Los pedidos requieren verificación de email del propietario
- Anti-enumeración: Mensajes genéricos que no revelan si un recurso existe
- Privacy by Design: Direcciones y teléfonos enmascarados en las respuestas
- Transacciones atómicas: Operaciones de escritura con rollback automático en caso de error
- Validación de queries: Solo se permiten sentencias
SELECTen el pool de lectura
---
Estructura del proyecto
├── src/
│ ├── index.ts # Servidor MCP + definición de herramientas
│ └── db.ts # Pools de conexión PostgreSQL
├── init-db/
│ ├── 01-schema.sql # Esquema de tablas + usuarios
│ └── 02-seed-data.sql # Datos de ejemplo (24 productos, 8 clientes, 8 pedidos)
├── docker-compose.yml # PostgreSQL containerizado
├── system-prompt.md # Prompt de sistema para agentes MCP
├── system-prompt-sql.md # Prompt de sistema para agentes SQL
├── MCP-TOOLS.md # Documentación detallada de herramientas
├── package.json
└── tsconfig.json---
Comandos útiles
npm run dev # Desarrollo con hot reload
npm run build # Compilar TypeScript
npm start # Ejecutar en producción
docker compose up -d # Iniciar PostgreSQL
docker compose down # Detener PostgreSQL
docker compose logs -f # Ver logs de la base de datos
