# MCP Server - Tienda de Suplementos Deportivos

Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://nodejs.org/) 18+
- [Docker](https://www.docker.com/) y Docker Compose

### 1. Clonar e instalar

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

### 2. Configurar variables de entorno

```bash
cp .env.example .env
```

El archivo `.env` contiene:

```env
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

```bash
docker compose up -d
```

Esto crea la base de datos PostgreSQL con el esquema y datos de ejemplo automáticamente.

### 4. Iniciar el servidor

```bash
# 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`:

```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:**

```env
# 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:

```bash
# 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:

```sql
-- 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:

```sql
-- 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.):

```json
{
  "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](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

```bash
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
```