MCP 服务器

Superprecio MCP Server

Enables AI assistants to search products, compare prices, and find the best deals across multiple supermarkets in Argentina through Superprecio's price comparison API. Transforms Claude into an expert shopping assistant for Latin American grocery shopping.

README

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:

search_products - Search for products by name across all supermarkets
search_by_code - Find products by EAN/barcode
compare_prices - Compare prices and find the best deals
get_best_deals - Discover current promotions and discounts
send_notification - Send push notifications about deals (requires Firebase)
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": ["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:

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

{
  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