README.md•7.66 kB
# Superprecio MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with access to Superprecio's price comparison functionality for supermarkets in Argentina (with plans to expand to all Latin America).
## Overview
This MCP server transforms Claude (or any MCP-compatible AI assistant) into an expert price comparison assistant for Argentina. It provides real-time access to product prices, deals, and availability across multiple supermarkets.
## Features
### 🛠️ Tools
The server provides 6 powerful tools:
1. **search_products** - Search for products by name across all supermarkets
2. **search_by_code** - Find products by EAN/barcode
3. **compare_prices** - Compare prices and find the best deals
4. **get_best_deals** - Discover current promotions and discounts
5. **send_notification** - Send push notifications about deals (requires Firebase)
6. **subscribe_device** - Subscribe devices to price alerts (requires Firebase)
### 📚 Resources
- **supermarket://list** - List of all available supermarkets
- **supermarket://[id]/info** - Detailed information about a specific supermarket
### 💬 Prompts
- **price_expert** - Transform Claude into an Argentina shopping expert
## Prerequisites
- Node.js 18.0.0 or higher
- Access to [Superprecio API](https://superprecio.ar) (production) or a local instance
## Installation
### Option 1: Use with npx (Recommended)
Once published to npm, you can use directly with:
```bash
npx superprecio-mcp
```
### Option 2: Install Globally
```bash
npm install -g superprecio-mcp
```
### Option 3: Local Development
```bash
# Clone the repository
git clone https://github.com/bunkerapps/superprecio_mcp.git
cd superprecio_mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run the server
npm start
```
## Configuration
Create a `.env` file in the project root:
```bash
# Copy the example file
cp .env.example .env
```
Edit `.env` with your settings:
```env
# Superprecio API URL (required)
# Use production API or your local instance
SUPERPRECIO_API_URL=https://superprecio.ar
# Request timeout in milliseconds (optional)
REQUEST_TIMEOUT=30000
# Enable debug logging (optional)
DEBUG=false
```
## Usage with Claude Desktop
Add this server to your Claude Desktop configuration:
### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"superprecio": {
"command": "npx",
"args": ["superprecio-mcp"],
"env": {
"SUPERPRECIO_API_URL": "https://superprecio.ar"
}
}
}
}
```
### Windows
Edit `%APPDATA%/Claude/claude_desktop_config.json` with the same configuration.
### Using Local Installation
If you installed locally or are developing:
```json
{
"mcpServers": {
"superprecio": {
"command": "node",
"args": ["/absolute/path/to/superprecio_mcp/build/index.js"],
"env": {
"SUPERPRECIO_API_URL": "https://superprecio.ar"
}
}
}
}
```
## Example Conversations
Once configured, you can ask Claude:
### Search for Products
```
You: "Busca el arroz más barato"
Claude: *Uses search_products and compare_prices tools*
"El arroz más barato está en [Supermercado] por $2,450..."
```
### Compare Prices
```
You: "Compara precios de leche en todos los supermercados"
Claude: *Uses compare_prices tool*
"Aquí está la comparación de precios de leche:
1. Supermercado A: $850
2. Supermercado B: $750 🏆 MEJOR PRECIO
3. Supermercado C: $890
¡Puedes ahorrar $140 comprando en Supermercado B!"
```
### Find Best Deals
```
You: "¿Cuáles son las mejores ofertas de hoy en cereales?"
Claude: *Uses get_best_deals tool*
"Aquí están las mejores ofertas en cereales:
1. Corn Flakes en [Supermercado] - $2,100 (15% OFF)
2. ..."
```
### Use the Price Expert Prompt
```
You: "Use the price_expert prompt"
Claude: *Becomes an Argentina shopping expert*
"¡Hola! Soy tu experto en supermercados de Argentina.
¿Cómo puedo ayudarte a ahorrar dinero hoy?"
```
## API Reference
### Tools
#### search_products
```typescript
{
query: string; // Product name (e.g., "leche descremada")
maxResults?: number; // Results per store (1-50, default: 9)
sortBy?: string; // "OrderByTopSaleDESC" | "OrderByPriceASC" | "OrderByPriceDESC"
}
```
#### search_by_code
```typescript
{
code: string; // EAN/barcode (usually 13 digits)
}
```
#### compare_prices
```typescript
{
productName: string; // Product to compare
maxResults?: number; // Results to analyze per store (1-20, default: 5)
}
```
#### get_best_deals
```typescript
{
category: string; // Category (e.g., "lácteos", "cereales")
maxResults?: number; // Deals per store (1-30, default: 10)
}
```
#### send_notification
```typescript
{
title: string; // Notification title
message: string; // Notification body
deviceToken?: string; // Optional: specific device (else broadcasts)
data?: object; // Optional: custom data
}
```
#### subscribe_device
```typescript
{
deviceToken: string; // Firebase Cloud Messaging token
}
```
### Resources
- `supermarket://list` - Returns JSON with all supermarkets
- `supermarket://[id]/info` - Returns JSON with specific supermarket details
### Prompts
- `price_expert` - Takes optional `focus` argument
## Development
```bash
# Install dependencies
npm install
# Watch mode (rebuilds on changes)
npm run dev
# Build for production
npm run build
# Run built server
npm start
```
## Architecture
```
superprecio_mcp/
├── src/
│ ├── index.ts # Main MCP server
│ ├── client/
│ │ └── superPrecioApi.ts # HTTP client for Superprecio API
│ ├── tools/ # MCP tool implementations
│ ├── resources/ # MCP resource handlers
│ ├── prompts/ # MCP prompt templates
│ └── types/ # TypeScript type definitions
├── build/ # Compiled JavaScript
└── package.json
```
## How It Works
1. **MCP Server**: Runs as a stdio-based server that communicates with Claude
2. **HTTP Client**: Makes requests to your Superprecio API instance
3. **Tools**: Expose Superprecio functionality as MCP tools
4. **Resources**: Provide access to supermarket data
5. **Prompts**: Transform Claude into a shopping expert
## Troubleshooting
### "Could not connect to Superprecio API"
- Verify API is accessible: `curl https://superprecio.ar`
- Check `SUPERPRECIO_API_URL` in your configuration
- Ensure there are no firewall issues
### "Unknown tool" errors
- Restart Claude Desktop after configuration changes
- Verify the MCP server is running (check Claude Desktop logs)
### Debug Mode
Enable debug logging:
```env
DEBUG=true
```
This will log all API requests/responses to stderr.
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Credits
- Built with [Model Context Protocol SDK](https://github.com/anthropics/model-context-protocol)
- Integrates with [Superprecio](https://superprecio.ar)
## Support
For issues and questions:
- GitHub Issues: [https://github.com/bunkerapps/superprecio_mcp/issues](https://github.com/bunkerapps/superprecio_mcp/issues)
- Superprecio Website: [https://superprecio.ar](https://superprecio.ar)
---
Made with ❤️ in Argentina for Latin American shoppers