# Conector MercadoLibre para Claude (copia personal)

Conecta tu cuenta de vendedor de MercadoLibre a Claude Desktop para consultar ventas, publicaciones, preguntas, competencia y precios en lenguaje natural.

Basado en un proyecto de licencia MIT de Algoritmo Digital (ver `LICENSE`). Esta copia es de uso personal: sin telemetría, sin enlaces a servicios del autor y sin la skill que enviaba publicaciones a un GPT externo.

```
Claude Desktop ──MCP──► este conector ──OAuth 2.0 + PKCE──► API oficial de MercadoLibre
```

## Instalación (Chile)

Necesitas Claude Desktop y [Node.js LTS](https://nodejs.org) instalados.

**1. Activa tu página de autorización (una sola vez).**
En este repositorio de GitHub: *Settings → Pages → Build and deployment → Deploy from a branch → rama `main`, carpeta `/docs` → Save*.
Tu dirección será: `https://ronaldramirez09.github.io/mercadolibre-mcp/conectar.html`

**2. Crea tu aplicación en MercadoLibre.**
Entra a [developers.mercadolibre.cl](https://developers.mercadolibre.cl) → *Mis aplicaciones* → *Crear nueva aplicación*.
- **URI de redirect** (exacta, sin barra final): `https://ronaldramirez09.github.io/mercadolibre-mcp/conectar.html`
- **Scopes:** `read`, `write` y `offline_access`.

Anota el **App ID** y el **Secret Key**. El Secret es como una contraseña: no lo compartas ni lo subas a GitHub.

**3. Agrega el conector a Claude Desktop.**
Abre `claude_desktop_config.json` (Windows: `Win + R` → `%APPDATA%\Claude\claude_desktop_config.json`; Mac: Claude → Settings → Developer → Edit Config) y agrega:

```json
{
  "mcpServers": {
    "mercadolibre": {
      "command": "npx",
      "args": ["-y", "github:ronaldramirez09/mercadolibre-mcp"],
      "env": {
        "ML_APP_ID": "TU_APP_ID",
        "ML_APP_SECRET": "TU_SECRET_KEY",
        "ML_SOLO_LECTURA": "1",
        "ML_SITE": "MLC"
      }
    }
  }
}
```

Reinicia Claude Desktop por completo.

**4. Conecta tu cuenta.** En un chat nuevo: *"conecta mi cuenta de MercadoLibre"*. Abre el link, autoriza, copia el código que aparece y pégaselo a Claude.

## Modo solo lectura

Con `"ML_SOLO_LECTURA": "1"` las herramientas que modifican tu tienda no existen. Pueden consultar, pero no cambiar nada. Cuando quieras permitir cambios (precios, stock, responder preguntas), borra esa línea y reinicia Claude. Aun así, pídele que te muestre el cambio exacto antes de aplicarlo.

Herramientas que escriben en tu tienda: `ml_actualizar_publicacion`, `ml_crear_publicacion`, `ml_responder_pregunta`, `ml_aceptar_promocion`, `ml_subir_clip`, `ml_borrar_clip` y `ml_desconectar`.

## Qué hace

Consultas: ventas y métricas, órdenes y envíos, publicaciones y visitas, preguntas, reputación, comisiones, rentabilidad, Product Ads, tendencias de búsqueda y competencia. Hay 5 "trabajadores" opcionales que vigilan precios, ventas, ranking y rivales mientras Claude está abierto (solo leen datos, no modifican tu cuenta). Las skills de la carpeta `skills/` convierten las herramientas en flujos completos.

## Privacidad

- Tus tokens se guardan solo en tu computador: `~/.meli-sellers-mcp/` (permisos 0600).
- Las únicas conexiones son a la API y al login de MercadoLibre, y a la comprobación de versión de **este** repositorio.
- Son opcionales y están apagados por defecto: el aviso por webhook (`ML_TRABAJADORES_WEBHOOK`) y la exportación a una planilla de Google (`docs/drive/`).

## Si algo falla

| Síntoma | Solución |
|---|---|
| El conector no aparece | Cierra Claude del todo (también desde la bandeja) y revisa el JSON en jsonlint.com |
| "invalid redirect_uri" | La URI en tu app de MercadoLibre debe ser idéntica a la de tu página, sin barra final |
| "code inválido" | El código vence en minutos y sirve una vez: repite "conecta mi cuenta" |
| La conexión se corta cada 6 horas | Falta el scope `offline_access` en tu app |
| Error 404 en la página de autorización | Revisa el paso 1 (Pages activado en `main` / `/docs`) y espera 1–2 minutos |

## Desarrollo

```
npm install
npm test     # pruebas contra un MercadoLibre simulado
```

Licencia MIT (ver `LICENSE`).