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 (production) or a local instance

Installation

Option 1: Use with npx (Recommended)

Once published to npm, you can use directly with:

npx superprecio-mcp

Option 2: Install Globally

npm install -g superprecio-mcp

Option 3: Local Development

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

# Copy the example file
cp .env.example .env

Edit .env with your settings:

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

{
  "mcpServers": {
    "superprecio": {
      "command": "npx",
      "args": ["-y", "superprecio-mcp"]
    }
  }
}

Note: The server uses https://superprecio.ar by default. For local development, add:

"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:

{
  "mcpServers": {
    "superprecio": {
      "command": "node",
      "args": ["/absolute/path/to/superprecio_mcp/build/index.js"]
    }
  }
}

For local development, override the API URL:

"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

{
  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

{
  code: string;  // EAN/barcode (usually 13 digits)
}

compare_prices

{
  productName: string;  // Product to compare
  maxResults?: number;  // Results to analyze per store (1-20, default: 5)
}

get_best_deals

{
  category: string;     // Category (e.g., "lácteos", "cereales")
  maxResults?: number;  // Deals per store (1-30, default: 10)
}

send_notification

{
  title: string;          // Notification title
  message: string;        // Notification body
  deviceToken?: string;   // Optional: specific device (else broadcasts)
  data?: object;          // Optional: custom data
}

subscribe_device

{
  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

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

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
• Integrates with Superprecio

Support

For issues and questions:

• GitHub Issues: https://github.com/bunkerapps/superprecio_mcp/issues
• Superprecio Website: https://superprecio.ar

Made with ❤️ in Argentina for Latin American shoppers