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

• Node.js 18+
• Docker y Docker Compose

1. Clonar e instalar

git clone https://github.com/sebastiancastillorock/mcpserverecommerce.git
cd mcpserverecommerce
npm install

2. Configurar variables de entorno

cp .env.example .env

El 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_db

3. Levantar la base de datos

docker compose up -d

Esto 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 start

El 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_DB

Ejemplos:

# 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/postgres

Opció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.sql

Opció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_URL y DATABASE_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 MCP
• system-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 SELECT en 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