# 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": ["-y", "superprecio-mcp"]
    }
  }
}
```

**Note:** The server uses `https://superprecio.ar` by default. For local development, add:
```json
"env": {
  "SUPERPRECIO_API_URL": "http://localhost:3000"
}
```

### 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"]
    }
  }
}
```

For local development, override the API URL:
```json
"env": {
  "SUPERPRECIO_API_URL": "http://localhost:3000"
}
```

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