OFIMA Celulares — MCP Server

Servidor MCP que expone dos herramientas para consultar en tiempo real el inventario y el plan retoma de celulares desde OFIMA.

Herramientas disponibles

consultar_stock

Consulta los equipos disponibles en bodega: modelos, colores, condición, unidades y precio de venta.

Comportamiento de búsqueda: usa LIKE parcial, así que iphone 15 devuelve iPhone 15, 15 Plus, 15 Pro y 15 Pro Max — pero NO el 14 ni el 16.

Respuesta: lista de modelos agrupados, cada uno con stock_total y sus variantes (estado, color, unidades, bodegas, precio).

consultar_retoma

Consulta cuánto recibe un cliente al entregar su equipo usado como parte de pago (plan retoma).

Respuesta: lista de modelos con sus variantes de condición (Seminuevo Grado A, Usado Grado B…) y el precio_recibe correspondiente.

Related MCP server: store-ops-mcp

API REST (api.py)

Autenticación con header X-API-Key: <API_REST_KEY> o query ?key=<API_REST_KEY>.

/stock cruza el inventario con las promociones cargadas sin tocar la base de OFIMA. Por defecto omite las variantes con stock = 0 (usa incluir_sin_stock=true para incluirlas). Cada variante trae precio como precio final a ofrecer; cuando hay promoción, precio_es_promocional es true, precio_antes trae el valor anterior y promo_mensaje la frase lista para el cliente. También se devuelven promociones_vigentes y resumen_promociones. Las promociones sin unidades salen en promociones_sin_stock cuando se busca con q. El cruce es por SKU (normalizado) contra el código OFIMA, luego por nombre exacto y por nombre específico contenido en la descripción.

La búsqueda de /stock y /retoma ignora la unidad de capacidad y la condición: q=iphone 14 pro max 256 gb se busca como iphone 14 pro max 256, y q=iphone 17 seminuevo como iphone 17. Si el modelo envía solo el nombre, devuelve todas las capacidades y la IA filtra la que pidió el cliente.

La búsqueda respeta las variantes: q=iphone 17 pro no devuelve el 17 Pro Max; q=iphone 17 sí devuelve toda la familia 17.

Promociones

El archivo debe tener el encabezado exacto:

SKU ;NOMBRE ;VALOR ANTES ;VALOR DESCUENTO

Al importar se borran todas las promociones anteriores y se insertan las nuevas en una sola transacción. Se aceptan .csv (separador ; o ,) y .xlsx. Los valores se interpretan como pesos: 1.234.567,89, $ 1,234,567.89 y 1234567 son válidos.

La tabla public.promociones se crea automáticamente en la base DATABASE_URL.

Variables de entorno

Copia .env.example a .env y completa los valores:

# SQL Server — OFIMA (stock en tiempo real)
SQLSERVER_DRIVER=ODBC Driver 17 for SQL Server
SQLSERVER_HOST=<host>
SQLSERVER_DB=<base_de_datos>
SQLSERVER_USER=<usuario>
SQLSERVER_PASSWORD=<contraseña>

# PostgreSQL — Lista de precios retoma (Railway)
PRECIOS_DATABASE_URL=postgresql://user:pass@host:5432/db

# Puerto del servidor HTTP (Railway lo inyecta automáticamente)
PORT=8000

Arranque

HTTP (Railway / producción)

python mcp_server.py

El servidor queda disponible en http://0.0.0.0:$PORT/mcp.

Stdio (integración local con Claude Desktop, Cursor, etc.)

fastmcp run mcp_server.py

Estructura del proyecto

mcpOfima/
├── mcp_server.py        # Servidor MCP — consultar_stock y consultar_retoma
├── api.py               # REST API — stock, retoma y promociones + interfaz web
├── busqueda.py          # Búsqueda por tokens (palabras completas)
├── promociones.py       # Carga CSV/XLSX y persistencia en PostgreSQL
├── promociones_ui.html  # Interfaz web simple
├── Plantilla.csv        # Plantilla de importación
├── db_sqlserver.py      # Helper de conexión a SQL Server (OFIMA)
├── replicate.py         # Script de replicación OFIMA → PostgreSQL
├── requirements.txt
├── Dockerfile
├── Procfile
└── .env