# venue-ops-mcp

An MCP server that gives Claude or any MCP client direct, read-only access to
the daily trading figures of a multi-site restaurant group — and, more to the
point, to the numbers where money leaves without anyone writing it down.

```
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.
```

## Why this exists

Most reporting tools answer the question everybody already asks: what did we
sell? Sales are the easy number. They are on the till, on the dashboard, in
the WhatsApp group by ten past midnight.

The numbers that decide whether a site makes money are **discounts, comped
items and voided tickets** — the control block — and they almost never reach a
daily report. A void rate sliding from 1% to 4% over three weeks does not look
like anything on any given night. It looks like a bad Tuesday, then a quiet
Thursday. It only looks like a problem when you compare a window against the
window before it, which is what this server does.

The thresholds here are not copied from a statistics textbook. They come from
having run venues.

## Tools

| Tool | What it answers |
|---|---|
| `venue_ops_list_venues` | Which sites exist and what period the data covers |
| `venue_ops_get_day` | Everything about one day: sales by channel, covers, average ticket, control block, labour |
| `venue_ops_compare_weekday` | Was this Saturday actually bad, or does it just feel bad? |
| `venue_ops_period_summary` | Totals for a range, per venue and for the group |
| `venue_ops_find_anomalies` | What is moving against its own baseline, in euros |

Every tool is read-only, annotated as such, and takes `response_format:
"markdown"` for a person or `"json"` for a program.

### The two shapes of anomaly

`venue_ops_find_anomalies` compares the last 7 days against the 28 before them
and reports two different things, because they mean different things:

- **Drift** — the whole recent window has moved. An unfixed rota, a till
  problem, a manager who has started comping to keep the peace. This is the
  expensive one and the one nobody spots.
- **Spike** — one day far outside the baseline. Usually a promotion nobody
  logged. Cheap to explain, worth confirming.

Findings under 40 EUR are dropped. They are real and they are not worth a
phone call, and a report that cries wolf gets ignored by week three.

## The data

`data/operations.json` is **synthetic**. Three venues, 182 days, generated by
`scripts/generate_data.py` from a fixed seed so results are reproducible. It
is not a real business and no real business is identifiable from it.

The numbers are invented; the *shape* is not. Weekday seasonality, the
dine-in/delivery split, discount and void rates and labour percentage all sit
inside the bands you see in casual dining.

Three anomalies are planted on purpose, so the detection has something real to
find and so anyone can check that it works:

| Venue | What | When |
|---|---|---|
| BCN-01 | Void rate drifts 0.9% → 5.2% and stops | 15 Jun – 5 Jul 2026 |
| MAD-02 | Labour percentage blows out to 41% for one week | 6 – 12 Apr 2026 |
| MAD-01 | Two isolated discount days at 14% | 9 May, 18 Jul 2026 |

To point this at a real point-of-sale system, replace the loader in
`venue_ops_mcp/data.py`. The tool layer does not care where rows come from.

## Install

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

## Use it with Claude Desktop

Add this to `claude_desktop_config.json`:

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

Restart Claude Desktop. Then ask it things like:

- *Which venues do we have?*
- *How did Gran Via do last Saturday compared with the Saturdays before it?*
- *Check Barcelona for problems in the week ending 5 July.*
- *What did the group do in July?*

## Verify it

```bash
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` asserts that the Barcelona drift is still detected and that a
clean window produces **no** findings. A detector that fires on everything is
worse than no detector, so both directions are tested.

## Built with

Python 3.10+, the MCP Python SDK (`MCPServer`, stdio transport), Pydantic v2
for input validation. No external services, no credentials, no network calls —
the server only reads a local file.

## Licence

MIT.