Skip to main content
Glama

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.

Related MCP server: data-refinery

Install

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:

git clone https://github.com/ranadhir19/cartefetch
cd cartefetch && pip install -e ".[rendered,mcp]"

CLI

# 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

cartefetch serve        # stdio

Client configuration (Claude Desktop / any MCP client):

{
  "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

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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      The owner-verified local business data + service & menu-price layer for AI agents. Owner-authored business profiles where every response carries provenance — verification level, completeness score, freshness timestamps, and upstream sources. * Search & profiles — find businesses by name, category, city, or geo-radius; full profiles with contacts, hours, media, ratings. * Price layer
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query structured data refined from unstructured web sources, including developer breaking changes, B2B pricing matrices, regulatory compliance, semantic search, and on-demand URL refinement.
      1
      Business Source 1.1
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to save reusable extraction recipes for public web pages, inspect page structures, and fetch fresh JSON or TSV data over plain HTTP, with a headless browser fallback when needed.
      68 npm
      MIT