内容
# MCP Extra Mercado 服务器
这是一个用Python编写的MCP（Model Context Protocol）服务器，直接与Extra Mercado的API（`api.vendas.gpa.digital`）交互。它允许进行搜索、创建购物车、添加商品到购物车、查看当前购物车内容以及列出/查看旧订单的详细信息，而无需视觉自动化或直接与Chrome浏览器交互。
该服务器在`~/.mcp-extramercado.json`文件中持久存储其身份验证凭证和首选项（例如商店和默认地址），以便于日常使用。
## 可用工具
1. `set_auth`: 在`~/.mcp-extramercado.json`中保存身份验证的JWT令牌。
2. `set_preferences`: 在本地配置文件中保存配送首选项（`storeId`、`addressId`、`storeDeliveryTypeId`、`zipCode`）。
3. `list_addresses`: 返回用户账户中注册的配送地址，以简化首选项选择。
4. `list_stores`: 返回特定邮政编码（`zipCode`）的可用商店和配送类型。
5. `search_products`: 按关键词在Extra Mercado上搜索商品。
6. `create_basket`: 创建一个新的购物车。如果省略，则使用`set_preferences`中配置的`storeId`、`addressId`和`storeDeliveryTypeId`。
7. `add_to_cart`: 将特定数量的商品添加到购物车中。
8. `get_cart`: 返回当前购物车的内容和商品。
9. `list_orders`: 列出已下订单的历史记录。
10. `get_order_details`: 返回特定订单的详细信息（包括购买的商品列表）。
## 安装和运行
服务器通过标准_stdio_进行通信，不依赖外部依赖项（仅使用Python 3的标准库）。
### 克劳德桌面配置
将以下配置添加到您的MCP配置文件中（例如`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"mcp-extramercado": {
"command": "/Users/igormspc/Projects/labs/mcp-extramercado/server.py"
}
}
}
```
## 如何配置身份验证和首选项
由于Extra Mercado需要账户和位置选择来管理购物车，您需要在第一次运行过程中遵循以下配置步骤：
1. **设置身份验证：**
访问Extra Mercado网站，在登录状态下，打开开发者控制台（F12），通过执行以下操作获取会话令牌：
```javascript
localStorage.getItem("USER_TOKEN")
```
然后，通过传递此令牌调用`set_auth`工具：
```json
{
"token": "您的JWT令牌"
}
```
2. **发现地址ID：**
设置令牌后，调用`list_addresses`工具以返回注册的地址。确定您首选地址的ID（`id`）。
3. **发现商店和配送类型：**
使用您的配送地址邮政编码调用`list_stores`工具：
```json
{
"zipCode": "<邮政编码>"
}
```
从返回值中选择所需的商店选项，并获取`storeid`（例如839）和`typeid`（例如1058）的值。
4. **保存您的首选项：**
调用`set_preferences`工具，提供您选择的ID：
```json
{
"storeId": 839,
"addressId": <地址ID>,
"storeDeliveryTypeId": <配送类型ID>,
"zipCode": "<邮政编码>"
}
```
5. **完成！**
现在，您可以调用`create_basket`工具而无需传递任何参数；它将自动使用保存的首选项数据初始化购物车。
