README_ES.md•6.85 kB
# Superprecio MCP Server
Servidor MCP (Model Context Protocol) que proporciona a asistentes de IA acceso a la funcionalidad de comparación de precios de Superprecio para supermercados en Argentina (con planes de expansión a toda Latinoamérica).
## Descripción
Este servidor MCP transforma a Claude (o cualquier asistente de IA compatible con MCP) en un experto asistente de comparación de precios para Argentina. Proporciona acceso en tiempo real a precios de productos, ofertas y disponibilidad en múltiples supermercados.
## Características
### 🛠️ Herramientas (Tools)
El servidor proporciona 6 herramientas poderosas:
1. **search_products** - Buscar productos por nombre en todos los supermercados
2. **search_by_code** - Encontrar productos por código EAN/barcode
3. **compare_prices** - Comparar precios y encontrar las mejores ofertas
4. **get_best_deals** - Descubrir promociones y descuentos actuales
5. **send_notification** - Enviar notificaciones push sobre ofertas (requiere Firebase)
6. **subscribe_device** - Suscribir dispositivos a alertas de precio (requiere Firebase)
### 📚 Recursos (Resources)
- **supermarket://list** - Lista de todos los supermercados disponibles
- **supermarket://[id]/info** - Información detallada sobre un supermercado específico
### 💬 Prompts
- **price_expert** - Transforma a Claude en un experto en compras de Argentina
## Características del Proyecto
- 🇦🇷 Iniciado en Argentina
- 🌎 Planes de expansión a toda Latinoamérica
- 💰 Moneda: Pesos argentinos ($)
- 🛒 Comparación en tiempo real de precios
- 🤖 Integración con Claude Desktop
- 📱 Soporte para notificaciones push
## Instalación
### Opción 1: Uso con npx (Recomendado)
Una vez publicado en npm:
```bash
npx superprecio-mcp
```
### Opción 2: Desarrollo Local
```bash
# Clonar el repositorio
git clone https://github.com/bunkerapps/superprecio_mcp.git
cd superprecio_mcp
# Instalar dependencias
npm install
# Compilar el proyecto
npm run build
# Ejecutar el servidor
npm start
```
## Configuración
Crear archivo `.env`:
```bash
cp .env.example .env
```
Editar `.env` con tu configuración:
```env
# URL de la API de Superprecio (requerido)
# Usar API de producción o instancia local
SUPERPRECIO_API_URL=https://superprecio.ar
# Timeout de peticiones en milisegundos (opcional)
REQUEST_TIMEOUT=30000
# Habilitar logs de debug (opcional)
DEBUG=false
```
## Uso con Claude Desktop
### macOS
Editar `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"superprecio": {
"command": "npx",
"args": ["superprecio-mcp"],
"env": {
"SUPERPRECIO_API_URL": "https://superprecio.ar"
}
}
}
}
```
### Windows
Editar `%APPDATA%/Claude/claude_desktop_config.json` con la misma configuración.
## Ejemplos de Conversación
### Buscar Productos
```
Vos: "Busca el arroz más barato"
Claude: *Usa search_products y compare_prices*
"El arroz más barato está en [Supermercado] por $2,450..."
```
### Comparar Precios
```
Vos: "Compara precios de leche en todos los supermercados"
Claude: *Usa compare_prices*
"Aquí está la comparación de precios de leche:
1. Supermercado A: $850
2. Supermercado B: $750 🏆 MEJOR PRECIO
3. Supermercado C: $890
¡Podés ahorrar $140 comprando en Supermercado B!"
```
### Encontrar Ofertas
```
Vos: "¿Cuáles son las mejores ofertas de hoy en cereales?"
Claude: *Usa get_best_deals*
"Aquí están las mejores ofertas en cereales:
1. Corn Flakes en [Supermercado] - $2,100 (15% OFF)
..."
```
### Usar el Prompt de Experto
```
Vos: "Use the price_expert prompt"
Claude: *Se convierte en experto de compras de Argentina*
"¡Hola! Soy tu experto en supermercados de Argentina.
¿Cómo puedo ayudarte a ahorrar plata hoy?"
```
## Desarrollo
```bash
# Instalar dependencias
npm install
# Modo watch (recompila automáticamente)
npm run dev
# Compilar para producción
npm run build
# Ejecutar servidor compilado
npm start
# Probar conexión a la API
npm test
```
## Arquitectura
```
superprecio_mcp/
├── src/
│ ├── index.ts # Servidor MCP principal
│ ├── client/
│ │ └── superPrecioApi.ts # Cliente HTTP para API de Superprecio
│ ├── tools/ # Implementación de herramientas MCP
│ ├── resources/ # Manejadores de recursos MCP
│ ├── prompts/ # Templates de prompts MCP
│ └── types/ # Definiciones de tipos TypeScript
├── build/ # JavaScript compilado
└── package.json
```
## Cómo Funciona
1. **Servidor MCP**: Se ejecuta como servidor basado en stdio que se comunica con Claude
2. **Cliente HTTP**: Hace peticiones a tu instancia de la API de Superprecio
3. **Tools**: Expone la funcionalidad de Superprecio como herramientas MCP
4. **Resources**: Proporciona acceso a datos de supermercados
5. **Prompts**: Transforma a Claude en un experto de compras
## Expansión a Latinoamérica
Este proyecto comenzó en Argentina y está diseñado para expandirse a otros países de Latinoamérica:
- 🇦🇷 Argentina (Actual)
- 🇨🇱 Chile (Planeado)
- 🇺🇾 Uruguay (Planeado)
- 🇵🇾 Paraguay (Planeado)
- 🇧🇷 Brasil (Planeado)
- 🇲🇽 México (Planeado)
- Y más...
El sistema está preparado para soportar múltiples monedas y configuraciones regionales.
## Solución de Problemas
### "Could not connect to Superprecio API"
- Verificar que la API sea accesible: `curl https://superprecio.ar`
- Revisar `SUPERPRECIO_API_URL` en tu configuración
- Asegurarse de que no haya problemas de firewall
### Claude no ve las herramientas
- Reiniciar Claude Desktop después de cambios en configuración
- Verificar que el servidor MCP esté ejecutándose (revisar logs de Claude Desktop)
### Modo Debug
Habilitar logging de debug:
```env
DEBUG=true
```
Esto registrará todas las peticiones/respuestas de la API en stderr.
## Contribuir
¡Las contribuciones son bienvenidas! Por favor:
1. Fork el repositorio
2. Crear una rama de feature
3. Hacer tus cambios
4. Agregar tests si es aplicable
5. Enviar un pull request
## Licencia
MIT License - ver archivo LICENSE para detalles
## Créditos
- Construido con [Model Context Protocol SDK](https://github.com/anthropics/model-context-protocol)
- Integra con [Superprecio](https://superprecio.ar)
## Soporte
Para issues y preguntas:
- GitHub Issues: [https://github.com/bunkerapps/superprecio_mcp/issues](https://github.com/bunkerapps/superprecio_mcp/issues)
- Sitio de Superprecio: [https://superprecio.ar](https://superprecio.ar)
---
Hecho con ❤️ en Argentina para compradores de Latinoamérica