cartefetch
by ranadhir19
README.md
# cartefetch
A restaurant's own website goes in; a **verified, structured, priced menu**
comes out — as a Python library, a CLI, and an MCP server.
Generic website-to-MCP bridges hand an agent a wall of unstructured page
text: no item/price pairs, no idea which restaurant the page belongs to.
cartefetch is built for the one job those tools cannot do — feeding a
priced-menu database you can trust:
- **Structured output.** Every extraction returns
`items[{name, description, price, currency, category, source_url}]`,
a restaurant identity block (name / address / phone as found on the
site), and a per-page extraction report.
- **Identity verification.** When you supply an expected name and/or
locality, items are returned only if the site's own evidence verifies
that restaurant. A mismatch is a named refusal
(`identity_mismatch`), never a silent attach. A chain page that
evidences many locations behind one shared menu refuses with
`chain_generic_requires_location` until a locality pins it down.
- **Honest failures.** No prices published → `no_priced_menu`. A bot wall
→ `bot_defence` (reported, never evaded). A JavaScript shell the
rendered layer could not resolve → `js_shell_unresolved`.
## How it extracts
Layers run in order; the first that yields items wins, and the winning
layer is named in the result:
1. **schema.org markup** — JSON-LD `Menu`/`MenuSection`/`MenuItem` graphs
and HTML microdata. The restaurant declared this data itself, so it is
trusted first.
2. **Rendered DOM** — Playwright loads the page, then a price-proximity
parser walks the rendered DOM: a short price element plus its item
container yields name, description, and the nearest preceding heading
as category.
3. **Static parsing** — DOM proximity over the fetched document, then
line-oriented price patterns over the flattened text.
The crawl is deliberately small: the URL you give plus up to two
same-host pages whose links say "menu". Non-menu prices are filtered by a
blocklist (gift cards, merchandise, totals and fees are not dishes), and
prose that merely mentions a price never becomes an item.
## Install
```bash
pip install cartefetch # library + CLI (static layers)
pip install "cartefetch[rendered]" # + Playwright for JS-rendered menus
pip install "cartefetch[mcp]" # + the MCP server
playwright install chromium # once, for the rendered layer
```
This repository is the source of truth; installing from a clone works too:
```bash
git clone https://github.com/ranadhir19/cartefetch
cd cartefetch && pip install -e ".[rendered,mcp]"
```
## CLI
```bash
# Extract (identity-checked) from a restaurant's own site
cartefetch extract https://nouracafe.com/menu-demo-1 \
--name "Noura's" --locality "St Johns, FL"
# What kind of menu source is this site?
cartefetch classify https://order.toasttab.com/online/some-place
# -> {"classification": "ordering_platform", "platform": "Toast", ...}
# Search a previous extraction
cartefetch extract https://example.com/menu > out.json
cartefetch search out.json "taco"
```
Exit code is `0` when extraction returns `status: "ok"`, `1` for any
named failure — the JSON on stdout always says which.
## MCP server
```bash
cartefetch serve # stdio
```
Client configuration (Claude Desktop / any MCP client):
```json
{
"mcpServers": {
"cartefetch": {
"command": "cartefetch",
"args": ["serve"]
}
}
}
```
Tools:
| Tool | Purpose |
| --- | --- |
| `extract_menu(url, expected_name?, expected_locality?)` | Full structured extraction with identity verification and a per-page report. |
| `classify_site(url)` | `ordering_platform` (with platform name), `priced_menu`, `unpriced_menu`, `none`, or `unreachable` with the named reason. |
| `menu_search(items, query)` | Filter a previous extraction's items by free text (name, description, category). Pure; no fetching. |
## Library
```python
from cartefetch import extract_menu, classify_site, menu_search
result = extract_menu(
"https://nouracafe.com/menu-demo-1",
expected_name="Noura's",
expected_locality="St Johns, FL",
)
assert result["status"] == "ok"
for item in result["items"]:
print(item["name"], item["price"], item["category"])
```
## Honest limits
- **Bot defences win sometimes.** Some ordering platforms block automated
fetches (Toast does from many networks). cartefetch reports
`bot_defence`; it does not try to evade. Running from a network the
platform accepts is the operator's call.
- **Unpriced menus are common.** Many independent restaurants publish a
menu with no prices. That is a data fact, not an extraction failure —
the status says so.
- **The rendered layer needs a browser.** Without Playwright/Chromium,
JS-only menus fall back to static layers and may end as
`js_shell_unresolved`. That status is the tool being honest, not stuck.
- **Heuristics, not magic.** Price-proximity parsing can mis-split an
exotic layout, and a name with an unusual comma can confuse the text
layer. Structured markup (layer 1) is preferred wherever a site offers
it, and the per-page report always shows which layer produced the items
and how many it found.
- **One price per item.** Multi-size pricing (small/large) records the
first price found in the item's container.
## Development
```bash
python -m venv .venv && .venv/bin/pip install -e ".[rendered,mcp,dev]"
.venv/bin/python -m pytest # fixture suite (no network needed)
.venv/bin/python validate.py # full harness: compile, tests, scans
```
## License
MIT — see `LICENSE`. Third-party dependencies and their licenses are
recorded in `COMPLIANCE.md`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues