{
  "markdown": "# Grocery MCP\n\n<!-- mcp-name: io.github.AndrewVG23/grocery-mcp -->\n\nA dedicated MCP and REST service that searches grocery retailers directly and\nreturns reviewable product links. It starts with:\n\n- Kettle Range Meat Co. — Milwaukee and Elm Grove\n- Outpost Natural Foods — Capitol Drive, State Street, Bay View, and Mequon\n\nThis service does **not** add products to carts, place orders, store retailer\ncredentials, or handle payment. Every response explicitly reports\n`cart_prefilled: false`; the user opens the links, adds products, and checks out\non the retailer's own site.\n\n## Setup\n\n```bash\npython3.12 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n```\n\n## Run\n\n```bash\npython -m grocery_mcp.server\npython -m grocery_mcp.server --http\n```\n\nHTTP endpoints:\n\n- MCP: `http://localhost:8080/mcp`\n- Health: `http://localhost:8080/health`\n- OpenAPI: `http://localhost:8080/docs`\n- Retailers: `http://localhost:8080/v1/retailers`\n- Product search: `http://localhost:8080/v1/products/search`\n- Handoffs: `POST http://localhost:8080/v1/handoffs`\n\nWhen `DATABASE_URL` is configured, handoffs and OAuth dynamic client\nregistrations are persisted in PostgreSQL. Without it, local development uses\nprocess memory.\n\n## MCP tools\n\n- `find_grocery_retailers`\n- `search_grocery_products`\n- `create_grocery_handoff`\n- `get_grocery_handoff`\n- `create_grocery_order_template`\n- `list_grocery_order_templates`\n- `create_handoff_from_template`\n\nExample handoff input:\n\n```json\n{\n  \"retailer\": \"kettle_range\",\n  \"location_id\": \"milwaukee\",\n  \"items\": [\n    {\"name\": \"boneless chicken thighs\", \"quantity\": 2, \"unit\": \"lb\"},\n    {\"name\": \"ground beef\", \"quantity\": 1, \"unit\": \"lb\"}\n  ]\n}\n```\n\n## Data behavior\n\nProduct names, prices, availability, and links come from each retailer's\npublic customer storefront at request time. These storefront interfaces are\nnot formal partner APIs and can change without notice. Responses include match\nconfidence, alternatives, and observation timestamps so clients can make this\nuncertainty visible.\n\nMatching requires strong token overlap, rejects obvious cross-category\nsubstitutions, and prefers available products. If no safe result exists, the\nitem is explicitly unmatched rather than replaced with a loosely related item.\n\nReusable templates persist the retailer, location, and normalized grocery\nitems. Running a template always performs fresh catalog searches and creates a\nnew review-only handoff.\n\n## Tests\n\n```bash\nruff check .\npytest\n```\n",
  "bytes": 2485,
  "sha": "342d32317da5369f80b5ba5713ddc96defd0c669705d866edd558cb9184176f1",
  "repo_slug": "andrewvg23/grocery_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_andrewvg23_grocery_mcp_0144623a/readme"
}