# Retail Inventory API — Server

Implements `retail-inventory-api.json` (the OpenAPI spec one level up) two
ways from one process: as the literal REST API the spec describes, and as
an MCP server exposing the same 8 operations as tools. Both are backed by
the same in-memory synthetic dataset, since the spec's `servers` entry
(`api.retailpartner.com`) is a design placeholder, not a real backend.

No persistence, logging, analytics, or caching — everything lives in
module-level Python lists for the life of the process. Rate-limit response
headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`) are present because
the spec requires them, but are fixed example values, not an enforced
limit — real enforcement would need exactly the kind of stateful
infrastructure this server is deliberately kept free of.

Auth matches the spec's stated model exactly: a Bearer API Key resolves to
one Partner, whose Store/Region/Brand scope filters every query. Demo keys
(see `retail_inventory_auth.py`):

| API Key | Partner | Scope |
|---|---|---|
| `rip_demo_store_key` | Priya Nair, Store Manager | Fernwood Riverside only |
| `rip_demo_region_key` | Carlos Mendez, Regional VP | Columbus, OH region |
| `rip_demo_brand_key` | Alice Smith, Inventory Planner | All Fernwood stores |

## Run locally

```
pip install -r requirements.txt
python retail_inventory_mcp_server.py
```

Serves on `http://127.0.0.1:8090` (or `$PORT` if set):

- **REST API** — the 8 paths exactly as declared in `retail-inventory-api.json`
  (`/stores`, `/stores/{storeId}/inventory-levels`, `/inventory-levels`,
  `/promotional-events`, `/sales-transactions`, `/inventory-recommendations`,
  `/inventory-recommendations/{recommendationId}/overrides`,
  `/metrics/full-price-sell-through-rate`) — no `/api` or version prefix, since
  none is in the spec.
- **MCP** — streamable-HTTP at `/mcp`, unchanged from before.
- **Docs** — `/` serves a Swagger UI page (backed by `/openapi.json`) for browsing the spec. Not part of `retail-inventory-api.json` itself, added so the deployed service has something to show a human visiting the root URL instead of a bare 404.

## Call the REST API

```
curl -H "Authorization: Bearer rip_demo_store_key" http://127.0.0.1:8090/stores
```

Errors follow the spec's RFC 9457 Problem Details format
(`application/problem+json`) for 400/401/404, exactly as documented.

## Connect an MCP client

Send `Authorization: Bearer <one of the demo keys above>` when connecting to
`http://127.0.0.1:8090/mcp`.