venue-ops-mcp

Un servidor MCP que le da a Claude o a cualquier cliente MCP acceso directo y de solo lectura a las cifras de operación diaria de un grupo de restaurantes con múltiples locales y, más concretamente, a los números por donde se va el dinero sin que nadie lo anote.

You: is anything leaking this week?

Claude: Eixample (BCN-01) — voided tickets have drifted from 1.55% of gross
to 4.60% over the last seven days, against a 28-day baseline. That is
799.16 EUR over the window. It is not a spike on one shift; it is a slope
across the whole week, which is the shape a till problem makes.

Por qué existe

La mayoría de las herramientas de informes responden a la pregunta que todo el mundo ya se hace: ¿qué vendimos? Las ventas son el número fácil. Están en el TPV, en el panel de control, en el grupo de WhatsApp a las doce y diez de la noche.

Los números que deciden si un local es rentable son descuentos, artículos compensados y tickets anulados — el bloque de control — y casi nunca llegan a un informe diario. Una tasa de anulación que pasa del 1% al 4% en tres semanas no parece nada en una noche cualquiera. Parece un mal martes, luego un jueves tranquilo. Solo parece un problema cuando comparas una ventana con la ventana anterior, que es lo que hace este servidor.

Los umbrales aquí no están copiados de un libro de texto de estadística. Vienen de haber gestionado locales.

Herramientas

Cada herramienta es de solo lectura, está anotada como tal y acepta response_format: "markdown" para una persona o "json" para un programa.

Las dos formas de anomalía

venue_ops_find_anomalies compara los últimos 7 días con los 28 anteriores e informa de dos cosas diferentes, porque significan cosas diferentes:

• Deriva — toda la ventana reciente se ha movido. Una rotación sin arreglar, un problema en el TPV, un gerente que ha empezado a compensar para mantener la paz. Esta es la cara y la que nadie detecta.

• Pico — un día muy fuera de la línea base. Normalmente una promoción que nadie registró. Barato de explicar, vale la pena confirmarlo.

Los hallazgos por debajo de 40 EUR se descartan. Son reales y no merecen una llamada telefónica, y un informe que da falsas alarmas se ignora a la tercera semana.

Los datos

data/operations.json es sintético. Tres locales, 182 días, generado por scripts/generate_data.py a partir de una semilla fija para que los resultados sean reproducibles. No es un negocio real y ningún negocio real es identificable a partir de él.

Los números son inventados; la forma no lo es. La estacionalidad semanal, la división entre cena en local y a domicilio, las tasas de descuento y anulación y el porcentaje de personal se encuentran dentro de los rangos que se ven en la restauración informal.

Se han plantado tres anomalías a propósito, para que la detección tenga algo real que encontrar y para que cualquiera pueda comprobar que funciona:

Para apuntar esto a un sistema de punto de venta real, reemplaza el cargador en venue_ops_mcp/data.py. La capa de herramientas no se preocupa de dónde vienen las filas.

Instalar

pip install -r requirements.txt
python scripts/generate_data.py

Usarlo con Claude Desktop

Añade esto a claude_desktop_config.json:

{
  "mcpServers": {
    "venue-ops": {
      "command": "python",
      "args": ["-m", "venue_ops_mcp.server"],
      "cwd": "/absolute/path/to/venue-ops-mcp"
    }
  }
}

Reinicia Claude Desktop. Luego pregúntale cosas como:

• ¿Qué locales tenemos?

• ¿Cómo le fue a Gran Vía el sábado pasado en comparación con los sábados anteriores?

• Revisa Barcelona en busca de problemas en la semana que termina el 5 de julio.

• ¿Qué hizo el grupo en julio?

Verificarlo

python scripts/smoke_test.py    # every tool, and the planted anomalies
python scripts/stdio_check.py   # the MCP handshake a real client performs

smoke_test.py afirma que la deriva de Barcelona sigue siendo detectada y que una ventana limpia no produce ningún hallazgo. Un detector que salta con todo es peor que ningún detector, así que se prueban ambas direcciones.

Construido con

Python 3.10+, el SDK de MCP para Python (MCPServer, transporte stdio), Pydantic v2 para la validación de entrada. Sin servicios externos, sin credenciales, sin llamadas de red — el servidor solo lee un archivo local.

Licencia

MIT.