# MCP WooCommerce

Servidor MCP + Bot de Telegram para gestionar tu tienda WooCommerce con IA.

Dos modos de uso:
- **MCP Server** — Conectá directamente desde Claude Desktop o Claude Code
- **Bot de Telegram** — Gestioná tu tienda desde Telegram con lenguaje natural y voz

## Features

- **13 herramientas** para gestionar productos, pedidos, clientes y reportes
- **Dual LLM** — Un modelo para consultas (rápido/barato) y otro para edición (preciso)
- **Soporte de voz** — Enviá audios por Telegram, se transcriben con Whisper
- **Multi-proveedor** — Soporta Claude, OpenAI (GPT) y Gemini como LLM
- **Deploy en Cloudflare Workers** — Gratis, siempre activo, sin servidor

## Herramientas disponibles

| Categoría | Herramienta | Descripción |
|-----------|------------|-------------|
| Productos | `list_products` | Listar con filtros (búsqueda, categoría, estado) |
| | `get_product` | Detalle de un producto por ID |
| | `create_product` | Crear producto nuevo |
| | `update_product` | Editar precio, stock, descripción, estado |
| | `delete_product` | Eliminar producto |
| Pedidos | `list_orders` | Pedidos recientes con filtros |
| | `get_order` | Detalle de un pedido |
| | `update_order_status` | Cambiar estado del pedido |
| Clientes | `list_customers` | Buscar por nombre o email |
| | `get_customer` | Detalle y historial de compras |
| Reportes | `sales_report` | Ventas del día/semana/mes |
| | `top_products` | Productos más vendidos |
| | `revenue_summary` | Resumen de ingresos completo |

## Requisitos previos

- Node.js 18+
- Cuenta de WooCommerce con API REST habilitada
- Para Telegram: Bot token de [@BotFather](https://t.me/BotFather)
- Para deploy: Cuenta de [Cloudflare](https://cloudflare.com) (gratis)
- API key de al menos un proveedor LLM (OpenAI, Anthropic o Google)

## Instalación

```bash
git clone https://github.com/tu-usuario/mcp-woocommerce.git
cd mcp-woocommerce
npm install
```

## Obtener credenciales de WooCommerce

1. En tu panel de WordPress: **WooCommerce → Ajustes → Avanzado → REST API**
2. Click en **"Agregar clave"**
3. Descripción: `MCP Bot`
4. Permisos: **Lectura/Escritura**
5. Click en **"Generar clave API"**
6. Guardá el **Consumer Key** (`ck_...`) y **Consumer Secret** (`cs_...`)

---

## Modo 1: MCP Server (Claude Desktop / Claude Code)

Conectá las herramientas de WooCommerce directamente a Claude sin intermediarios.

### Configuración en Claude Desktop

Editá tu archivo de configuración de Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["tsx", "src/mcp-server.ts"],
      "cwd": "/ruta/a/mcp-woocommerce",
      "env": {
        "WC_URL": "https://tu-tienda.com",
        "WC_CONSUMER_KEY": "ck_xxxxxxxxxxxxxxxxxxxxx",
        "WC_CONSUMER_SECRET": "cs_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Configuración en Claude Code

```bash
claude mcp add woocommerce \
  -e WC_URL=https://tu-tienda.com \
  -e WC_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxx \
  -e WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxx \
  -- npx tsx src/mcp-server.ts
```

### Probar localmente

```bash
WC_URL=https://tu-tienda.com \
WC_CONSUMER_KEY=ck_xxx \
WC_CONSUMER_SECRET=cs_xxx \
npm run mcp
```

---

## Modo 2: Bot de Telegram

Bot interactivo que responde mensajes de texto y voz usando IA.

### Arquitectura

```
Telegram (vos) → Cloudflare Worker (webhook) → LLM (tool calling) → WooCommerce API
       ← respuesta formateada ← datos/confirmación ←
```

### Crear bot de Telegram

1. Abrí [@BotFather](https://t.me/BotFather) en Telegram
2. Enviá `/newbot` y seguí las instrucciones
3. Guardá el **token** que te da
4. Mandá un mensaje a tu bot nuevo (un "hola")
5. Visitá `https://api.telegram.org/bot<TOKEN>/getUpdates` para obtener tu **Chat ID**

### Variables de entorno

Copiá el archivo de ejemplo:

```bash
cp .dev.vars.example .dev.vars
```

Editá `.dev.vars` con tus credenciales:

```env
# Telegram
TELEGRAM_BOT_TOKEN=tu-token
TELEGRAM_CHAT_ID=tu-chat-id

# WooCommerce
WC_URL=https://tu-tienda.com
WC_CONSUMER_KEY=ck_xxx
WC_CONSUMER_SECRET=cs_xxx

# LLM - Modo simple (un solo proveedor)
LLM_PROVIDER=openai
LLM_API_KEY=sk-xxx

# LLM - Modo dual (recomendado)
LLM_QUERY_PROVIDER=openai      # Para consultas: rápido y barato
LLM_QUERY_API_KEY=sk-xxx
LLM_EDIT_PROVIDER=claude       # Para edición: preciso y confiable
LLM_EDIT_API_KEY=sk-ant-xxx
```

### Sistema Dual LLM

El bot puede usar **dos LLMs diferentes** según el tipo de operación:

| Tipo | Proveedor recomendado | Modelo | Para qué |
|------|----------------------|--------|----------|
| Consultas | OpenAI | gpt-4o-mini / gpt-5.3 | Listar, buscar, reportes |
| Edición | Anthropic | claude-sonnet-4 | Crear, actualizar, eliminar |

El routing es automático: detecta si tu mensaje contiene palabras como "crear", "editar", "cambiar precio", etc.

Si configurás solo `LLM_PROVIDER` y `LLM_API_KEY`, usa un único modelo para todo.

### Soporte de voz (Whisper)

Enviá un mensaje de voz al bot y:
1. Se descarga el audio de Telegram
2. Se transcribe con **OpenAI Whisper** (`gpt-4o-mini-transcribe`)
3. Te muestra qué entendió
4. Procesa la consulta normalmente

Requiere `LLM_QUERY_API_KEY` con una API key de OpenAI (Whisper usa la misma key).

### Proveedores LLM soportados

| Proveedor | Valor de config | Modelos |
|-----------|----------------|---------|
| OpenAI | `openai` | gpt-4o, gpt-4o-mini, gpt-5.3-chat-latest |
| Anthropic | `claude` | claude-sonnet-4, claude-haiku-4 |
| Google | `gemini` | gemini-2.0-flash |

### Deploy en Cloudflare Workers

#### 1. Login en Cloudflare

```bash
npx wrangler login
```

#### 2. Deploy

```bash
npm run deploy
```

#### 3. Configurar secrets

```bash
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put TELEGRAM_CHAT_ID
npx wrangler secret put WC_URL
npx wrangler secret put WC_CONSUMER_KEY
npx wrangler secret put WC_CONSUMER_SECRET
npx wrangler secret put LLM_QUERY_PROVIDER
npx wrangler secret put LLM_QUERY_API_KEY
npx wrangler secret put LLM_EDIT_PROVIDER
npx wrangler secret put LLM_EDIT_API_KEY
```

#### 4. Configurar webhook de Telegram

```bash
curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://<tu-worker>.workers.dev/webhook"
```

O con el script incluido:

```bash
TELEGRAM_BOT_TOKEN=xxx WORKER_URL=https://tu-worker.workers.dev npx tsx scripts/set-webhook.ts
```

### Desarrollo local

```bash
npm run dev
```

Usa las variables de `.dev.vars` automáticamente.

---

## Estructura del proyecto

```
mcp-woocommerce/
├── src/
│   ├── index.ts              # Entry point Cloudflare Worker
│   ├── mcp-server.ts         # MCP Server (Claude Desktop/Code)
│   ├── bot/
│   │   ├── handler.ts        # Bot Telegram + webhook + tool execution
│   │   └── auth.ts           # Validación de Chat ID
│   ├── llm/
│   │   ├── provider.ts       # Abstracción LLM (Claude/OpenAI/Gemini)
│   │   └── tools.ts          # Definición de herramientas
│   ├── woocommerce/
│   │   ├── client.ts         # Cliente REST API v3
│   │   ├── products.ts       # Operaciones de productos
│   │   ├── orders.ts         # Operaciones de pedidos
│   │   ├── customers.ts      # Operaciones de clientes
│   │   └── reports.ts        # Reportes y análisis
│   └── utils/
│       └── formatter.ts      # Formateo para Telegram
├── scripts/
│   └── set-webhook.ts        # Script para configurar webhook
├── wrangler.toml              # Config Cloudflare Workers
├── .dev.vars.example          # Ejemplo de variables de entorno
└── package.json
```

## Seguridad

- Las API keys se almacenan como **secrets encriptados** en Cloudflare (nunca en el código)
- El bot solo responde a tu **Chat ID** configurado
- El MCP server lee credenciales de **variables de entorno** (nunca hardcodeadas)
- El archivo `.dev.vars` está en `.gitignore`

## Limitaciones (Cloudflare Workers free tier)

- Timeout de **30 segundos** por request
- **100,000 requests/día**
- Sin estado persistente entre requests (stateless)
- Webhook mode obligatorio (no polling)

## Licencia

MIT