# Sales Analyzer MCP Server

A remote [MCP](https://modelcontextprotocol.io) server that exposes sales anomaly
detection as tools Claude can call. It bundles a deterministic sample dataset — one
year of daily sales for a fictional café, "Bean & Leaf" — and analyzes it with robust
statistics (median absolute deviation), so anomalies like closures, pricing glitches,
and structural product declines are detected in code, not guessed by the model.

The server returns **only computed data**: no LLM calls, no API keys, fully stateless.
Built with the official MCP Python SDK (FastMCP) over the Streamable HTTP transport.

## Tools

| Tool | What it returns |
|------|-----------------|
| `list_weeks()` | The 53 weeks in the dataset with date ranges, row counts, and completeness |
| `analyze_week(week_number)` | Weekly revenue, totals by product, week-over-week changes, top movers, daily series, and flagged anomalies with severity and reason |
| `get_product_history(product_name)` | A product's full weekly units/revenue series |

Bad inputs (week 99, unknown product) return a clear `{"error": ...}` message instead
of failing.

## Project layout

- `server.py` — FastMCP server: transport, health check, and the three tools
- `analytics.py` — stdlib-only analytics: weekly aggregation + MAD-based anomaly detection
- `generate_sample_data.py` — seeded generator for the sample dataset (byte-identical every run)
- `data/sales_2025.csv` — the bundled dataset (regenerated at startup if missing)
- `test_client.py` — smoke test that exercises every tool against a running server

## Run locally

```bash
pip install -r requirements.txt
python server.py
```

The server listens on port 8000 (override with the `PORT` env var):

- Landing page / health check: `GET http://localhost:8000/` → an HTML page (HTTP 200)
- MCP endpoint: `http://localhost:8000/mcp`

Verify all tools in a second terminal:

```bash
python test_client.py
```

## Deploy to Render (free tier)

1. Push this repo to GitHub.
2. In the [Render dashboard](https://dashboard.render.com), click **New + → Blueprint**
   and select the repo — `render.yaml` configures everything (Python web service,
   free plan, `python server.py` start command).
   - Or manually: **New + → Web Service**, build command
     `pip install -r requirements.txt`, start command `python server.py`.
3. Wait for the deploy to go live. Your MCP endpoint is:

   ```
   https://<your-service>.onrender.com/mcp
   ```

4. Sanity-check it: opening `https://<your-service>.onrender.com/` in a browser shows
   the landing page (which also serves as the health check).

Note: free-tier services spin down after ~15 minutes of inactivity; the first request
after that takes ~30-60 seconds while the instance cold-starts. The server is stateless,
so this is harmless — retry once if a first call times out.

## Add to Claude as a custom connector

1. In Claude (web or desktop), go to **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter the URL **ending in `/mcp`**, e.g.
   `https://sales-analyzer-mcp.onrender.com/mcp`, and add it. No authentication is
   required.
4. In a chat, enable the connector from the tools menu, then ask something like:

   > Which weeks in the sales data look anomalous, and what happened in week 32?

Claude will call `list_weeks`, `analyze_week`, and `get_product_history` as needed and
reason over the returned figures.

## About the sample data

The dataset (6 products × 365 days of 2025) has realistic weekly rhythm, seasonality,
and growth, plus four hidden anomalies the detectors rediscover:

- a 5-day closure in mid-March (pipe burst),
- a one-day viral spike in May,
- a week of 10x-inflated Latte revenue in August (decimal error — units normal),
- a permanent Blueberry Muffin collapse from October (supplier problem).

The generator is seeded, so the CSV is identical on every run.