superprecio MCP

超级价格MCP服务器

一个模型上下文协议（MCP）服务器，为AI助手提供访问Superprecio在阿根廷超市价格比较功能的服务（并计划扩展至整个拉丁美洲）。

概述

这款MCP服务器将Claude（或任何兼容MCP的人工智能助手）转变为阿根廷的专业比价助手。它提供实时访问多家超市的产品价格、优惠和库存情况。

特点/功能

🛠️ 工具

服务器提供了6个强大的工具：

1. 搜索产品 - 在所有超市中按名称搜索产品
2. 按代码搜索 - 通过EAN/条形码查找产品
3. 比较价格 - 比较价格，寻找最优惠的交易
4. 获取最优惠交易 - 发现当前的促销和折扣
5. 发送通知 - 发送有关优惠的推送通知（需要Firebase）
6. 订阅设备 - 为设备订阅价格提醒（需要Firebase）

📚 资源

• supermarket://list 翻译成中文是：“超市://列表”。不过，这里的“supermarket://”通常不是标准的网址协议，它可能是一个特定应用或平台内部的链接格式，用于在应用内导航到某个列表页面。在实际中文语境中，我们可能会根据具体应用场景来翻译或解释这个链接，但基本意思是“指向超市（或某应用内的超市模块）的列表页面” - 所有可用超市的列表
• supermarket://\[id\]/info 翻译成中文是：“超市://\[商品ID\]/信息”。不过，这里的“supermarket://”并不是一个标准的网址协议，它更像是一个示例或特定应用内的路径格式，所以在实际翻译时，我们将其意译为“超市（或商品）信息查询”，并假设“\[id\]”代表某个商品的唯一标识符。因此，一个更自然的中文表达可能是：“查询商品（ID: \[id\]）的信息” - 关于特定超市的详细信息

💬 提示（或指令）

• 价格专家 - 把克劳德变成阿根廷购物专家

先决条件

• Node.js 18.0.0 或更高版本
• 访问/获取 Superprecio API （生产环境）或本地实例

安装

选项1：使用npx（推荐）

一旦发布到npm，您可以直接使用：

npx superprecio-mcp

选项2：全局安装

npm install -g superprecio-mcp

选项3：本地开发

# 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

配置

创建一个 .env 项目根目录下的文件：

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

编辑 .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

与Claude桌面版的使用

将此服务器添加到您的Claude Desktop配置中：

macOS（苹果电脑操作系统）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

注： 服务器使用 https://superprecio.ar 默认情况下。对于本地开发，请添加：

"env": {
  "SUPERPRECIO_API_URL": "http://localhost:3000"
}

Windows（微软视窗操作系统）

编辑 %APPDATA%/Claude/claude_desktop_config.json 具有相同的配置。

使用本地安装

如果您是本地安装或正在开发：

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

对于本地开发，请覆盖API URL：

"env": {
  "SUPERPRECIO_API_URL": "http://localhost:3000"
}

示例对话

一旦配置完成，您就可以向Claude询问：

搜索产品

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

比较价格

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

寻找最优惠交易

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

使用价格专家提示

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 参考文档

工具

搜索产品

{
  query: string;        // Product name (e.g., "leche descremada")
  maxResults?: number;  // Results per store (1-50, default: 9)
  sortBy?: string;      // "OrderByTopSaleDESC" | "OrderByPriceASC" | "OrderByPriceDESC"
}

按代码搜索

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

比较价格

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

获取最佳优惠

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

发送通知

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

订阅设备

{
  deviceToken: string;  // Firebase Cloud Messaging token
}

资源

• supermarket://list - 返回包含所有超市的JSON数据
• supermarket://[id]/info - 返回包含特定超市详细信息的JSON

提示

• price_expert - 接受可选参数 focus 论点；争论点

发展

# Install dependencies
npm install

# Watch mode (rebuilds on changes)
npm run dev

# Build for production
npm run build

# Run built server
npm start

建筑学

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

它是如何工作的

1. MCP服务器作为一个基于标准输入输出（stdio）的服务器运行，与Claude进行通信
2. HTTP 客户端向您的Superprecio API实例发出请求
3. 工具将Superprecio的功能作为MCP工具暴露出来
4. 资源提供超市数据访问权限
5. 提示将克劳德变成购物专家

故障排除

无法连接到Superprecio API

• 验证API是否可访问： curl https://superprecio.ar
• 检查 SUPERPRECIO_API_URL 在您的配置中
• 确保没有防火墙问题

“未知工具”错误

• 配置更改后重启Claude桌面版
• 验证MCP服务器是否正在运行（检查Claude Desktop日志）

调试模式

启用调试日志记录：

DEBUG=true

这会将所有API请求/响应记录到标准错误输出。

做出贡献

欢迎投稿！请：

1. 克隆该仓库
2. 创建一个特性分支
3. 做出你的更改
4. 如适用，请添加测试
5. 提交拉取请求

许可证

MIT 许可证 - 详见 LICENSE 文件

致谢/贡献者名单

• 构建于 模型上下文协议SDK
• 与……集成 超级价格

支持

对于问题和疑问：

• GitHub Issues：（可译为）GitHub 问题板块/议题
• Superprecio网站： https://superprecio.ar（该网址可译为“超级价格.ar”，但实际翻译时通常保留原网址不变，因为网址是特定的网络地址，不直接翻译其意义）

______________________________________________________________________

为拉丁美洲购物者倾情打造于阿根廷