Conecta tu asistente de IA (MCP)

StockAI habla el Model Context Protocol: un asistente de IA como Claude puede leer tu semáforo y decirte qué comprar hoy. Solo lee; nunca cambia nada.

MCP es el protocolo con el que los asistentes de IA se conectan a herramientas externas. StockAI ofrece un servidor MCP en tu propia instalación, para que le preguntes a tu asistente «¿qué compro hoy?» y la respuesta salga de tus datos, no de suposiciones.

Dónde está y cómo se entra

• La dirección es /api/v1/mcp en el dominio de tu instalación; la pantalla API la muestra completa en «Conecta tu asistente (MCP)».
• Se entra con una llave de API normal, en la cabecera Authorization: Bearer sk_live_.... Una llave «Solo leer» alcanza para todo.
• Comparte el mismo límite que la API: 120 llamadas por minuto por llave, y el tope diario de tu plan.
• Las preguntas se mandan con POST. Un GET a la misma dirección responde 405: el servidor no abre un canal de eventos, porque todo cabe en la respuesta de cada pregunta.

Las cinco herramientas

get_planning_context

Qué actualización está activa, con qué detalle (día, semana o mes) y sobre cuántos períodos se calculó todo lo demás. Es el punto de partida.

get_morning_briefing

El trabajo del día: los riesgos que vale la pena atender, el motivo de cada recomendación, el proveedor sugerido y el valor estimado. Es la herramienta para «¿qué compro hoy?».

get_inventory_status

El semáforo por producto (PEDIR_YA, PEDIR_PRONTO, OK, SOBRESTOCK, SIN_DATOS) con la cantidad a pedir y de dónde salió cada supuesto. Se puede filtrar por señal o por proveedor.

list_data_sources

Tus fuentes de ventas y cuándo se actualizó cada una, para saber si los números se basan en datos frescos.

get_training_status

Si una actualización terminó de entrenar: en cola, calculando, completada o fallida.

Las herramientas le advierten al asistente que SIN_DATOS significa «no sabemos», no «está bien», y que un valor marcado como supuesto de StockAI no es un dato tuyo. Así el asistente no te presenta como tranquilo algo que nadie midió.

Conectar tu cliente

1. Crea una llave «Solo leer» en Automatización.
2. Si tu cliente de IA acepta una URL, dale la dirección MCP de tu instalación con la cabecera Authorization: Bearer y tu llave.
3. Si es un cliente de escritorio que habla por la consola (stdin/stdout), como Claude Desktop, usa el archivo mcp_server/stockai_mcp.py del repositorio: es un solo archivo de Python sin dependencias. Define STOCKAI_URL (la dirección de tu instalación, sin barra al final) y STOCKAI_API_KEY (tu llave), y apunta tu cliente a ese archivo.
4. Pregúntale «¿qué compro hoy?». La respuesta sale del mismo trabajo del día que ves en el Panel de compras.

Por qué no escribe nada

Por MCP no se sube ningún archivo, no se entrena, no se registra ninguna orden y no se edita stock. No es un límite del rol: aunque uses una llave «Leer y escribir», el asistente solo lee. Un asistente de IA no puede mostrarte la tarjeta de confirmación ni ofrecerte deshacer, que es lo que StockAI exige antes de un cambio en tus datos. Esas acciones se quedan en la app y en la API, donde las dispara una persona que ve lo que pasó.