Frontline Copilot

Triaje de reseñas con IA para gerentes de tiendas minoristas.

Un sistema siempre activo que ingiere reseñas de clientes de cualquier fuente, utiliza Claude para clasificarlas por categoría y gravedad, y enruta las accionables a la lista de tareas de Airtable del gerente de tienda, con alertas de Slack en tiempo real para problemas críticos (seguridad alimentaria, conducta del personal, riesgos para la salud).

También se distribuye como servidor MCP para que los gerentes de tienda puedan consultar y hacer triaje de forma conversacional desde Claude Desktop.

Inspirado en la categoría emergente de copilotos de IA para operaciones de tienda.

El problema

Los gerentes de tienda de cadenas minoristas con múltiples ubicaciones se ahogan en las señales de las reseñas de clientes. La mayoría son ruido (elogios o quejas menores). Algunas son urgentes (seguridad alimentaria, discriminación, riesgo de lesiones). La mayoría de las herramientas exigen que el gerente lea todo para encontrar las pocas que importan: una batalla perdida a escala.

Frontline Copilot invierte esto. Claude lo lee todo; el gerente solo ve lo que requiere acción.

Related MCP server: Shopify MCP Server

Cómo funciona

┌────────────┐   ┌──────────────┐   ┌────────────┐   ┌────────────┐
│  Reviews   │──▶│ Classifier   │──▶│  Airtable  │──▶│   Slack    │
│  (JSON /   │   │ (Claude API, │   │  (task     │   │  (critical │
│   Google)  │   │  tool use)   │   │  tracker)  │   │   alerts)  │
└────────────┘   └──────────────┘   └────────────┘   └────────────┘
                        │
                        ▼
                 ┌──────────────┐
                 │  MCP server  │◀── Claude Desktop, Cursor, ...
                 │  (3 tools)   │
                 └──────────────┘

Cada reseña se clasifica en una de nueve categorías con una gravedad de 1 (positiva) a 5 (crítica). Las reseñas con gravedad ≥ 3 se convierten en tareas de Airtable; las de gravedad ≥ 4 además disparan una alerta de Slack.

Capturas de pantalla

Ejecución del pipeline de extremo a extremo

21 reseñas procesadas en ~60 segundos. 7 tareas creadas, 4 alertas críticas en tiempo real.

Airtable: tablero de tareas

Tareas ordenadas por gravedad, coloreadas por categoría. Esto es lo que ve un gerente de tienda.

Airtable: vista Kanban

Los mismos datos, agrupados por categoría. Distribución de incidencias de un vistazo.

Slack: alertas críticas en tiempo real

Tarjetas Block Kit con diseño orientado a la acción y enlace directo a la tarea de Airtable.

Stack tecnológico

• Python 3.10+ — dataclasses, tipos unión str | None, pathlib

• API de Anthropic Claude — clasificación mediante uso de herramientas (claude-haiku-4-5)

• API REST de Airtable — gestor de tareas, llamada directamente con requests

• Slack Incoming Webhooks — Block Kit para tarjetas de alerta enriquecidas

• MCP (Model Context Protocol) — interfaz conversacional mediante FastMCP

• Patrón adaptador para fuentes de reseñas (se incluye Mock; Google Places con stub)

Solo tres dependencias de terceros: anthropic, requests, mcp. Todo lo demás es biblioteca estándar.

Inicio rápido

# 1. Clone and install
git clone https://github.com/miguelpomarm/frontline-copilot
cd frontline-copilot
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets
cp .env.example .env
# ... edit .env with your keys (see setup section below)

# 3. Run the pipeline
python triage.py

# 4. Launch as an MCP server (optional)
python mcp_server.py

Configuración (una sola vez, ~10 minutos)

1. Clave de API de Anthropic

Consigue una en https://console.anthropic.com/. El nivel gratuito es suficiente para ejecuciones de demostración: 21 reseñas cuestan ~0,03 $.

2. Base de Airtable

Crea una nueva base con una tabla llamada Tasks y estos campos (nombres exactos):

A continuación, genera un token de acceso personal en https://airtable.com/create/tokens con los ámbitos data.records:read y data.records:write en tu base. Copia el token y el ID de la base (empieza por app..., se encuentra en la URL de tu base).

3. Slack Incoming Webhook

Crea una aplicación de Slack en https://api.slack.com/apps. Habilita Incoming Webhooks, añade un nuevo webhook que apunte al canal que deba recibir las alertas críticas y copia la URL del webhook.

4. Rellena .env

ANTHROPIC_API_KEY=sk-ant-...
AIRTABLE_API_KEY=pat...
AIRTABLE_BASE_ID=app...
AIRTABLE_TABLE_NAME=Tasks
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

5. Primera ejecución

python triage.py --limit 3 --dry-run   # sanity check, no side effects
python triage.py --limit 3             # small live run
python triage.py                       # full 21 reviews

Integración MCP (Claude Desktop)

Añade esto a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) y reinicia Claude Desktop:

{
  "mcpServers": {
    "frontline-copilot": {
      "command": "python",
      "args": ["/absolute/path/to/frontline-copilot/mcp_server.py"]
    }
  }
}

Después, dentro de Claude Desktop:

"¿Cómo está Aurora Times Square ahora mismo?"

Claude invocará get_store_health("times_square"), consultará Airtable y responderá con la instantánea actual: tareas abiertas, número de críticas, categoría principal.

Decisiones de diseño

Elecciones deliberadas que merece la pena destacar para un revisor:

Taxonomía cerrada + cubo Other Las categorías son una enumeración fija, no de formato libre. Esto garantiza un enrutamiento y unas métricas coherentes. Other es la vía de escape: se revisa periódicamente para ampliar la taxonomía basándose en datos reales en lugar de suposiciones a priori.

Uso de herramientas frente a ingeniería de prompts Claude devuelve una salida estructurada mediante un esquema de herramienta con aplicación de enumeración. Esto elimina los errores de análisis y evita que el LLM alucine una categoría fuera de la taxonomía.

Haiku 4.5 como modelo predeterminado Para una tarea de clasificación bien delimitada, Haiku es rápido (menos de un segundo), barato (~0,001 $ por reseña) y suficientemente preciso. En producción, solo esta decisión ahorra miles de dólares al mes con un volumen moderado.

Patrón adaptador para fuentes de reseñas ReviewSource es una interfaz abstracta. Se incluye con MockSource y un stub documentado de GooglePlacesSource. Cambiar a Yelp, TrustPilot o un feed propietario es una nueva subclase: el resto del pipeline no se toca.

Idempotencia por ID de reseña Reprocesar las mismas reseñas no crea tareas duplicadas. Se comprueba Airtable antes de cada creación.

Umbrales de gravedad como constantes ajustables ACTION_THRESHOLD y ALERT_THRESHOLD están a nivel de módulo. Los clientes con diferentes tolerancias cambian dos números, no código.

Síncrono frente a asíncrono para el MVP Procesa 21 reseñas secuencialmente en ~40 s. La variante asíncrona son ~15 líneas para intercambiar (AsyncAnthropic + asyncio.gather con un semáforo para los límites de velocidad). Para este volumen, la legibilidad gana a la velocidad.

El texto por encima de las estrellas El prompt indica explícitamente a Claude que pondere el texto de la reseña por encima de la valoración con estrellas. Una reseña de 4 estrellas que mencione seguridad alimentaria es de gravedad 5, no 2.

Hoja de ruta (no implementado)

• Endpoint de webhook FastAPI (POST /webhook/review) para la ingesta en tiempo real en lugar de ejecuciones por lotes.

• GooglePlacesSource: la interfaz del adaptador está hecha; la implementación real es ~1 hora de integración de API + lógica de reintentos.

• Procesamiento por lotes asíncrono consciente de los límites de velocidad para producción de alto volumen.

• Pruebas de extremo a extremo (Playwright / pytest con interacciones de API registradas) que verifiquen los efectos secundarios de Airtable/Slack.

• Umbrales configurables por cliente mediante config.yaml.

Licencia

MIT: consulta LICENSE.

Creado por Miguel Pomar Martínez como pieza de portafolio técnico.