# foodnear.me

> AI-native restaurant discovery infrastructure — structured menus for AI agents via Menu Protocol.

foodnear.me is the canonical discovery layer for AI agents seeking reliable, owner-approved restaurant menu data. We provide the Menu Protocol standard (a Schema.org superset optimized for agent parsing) and Agent Discovery Optimization (ADO) scoring to help restaurants become machine-discoverable.

Unlike delivery platforms that scrape menus or lock restaurants into 20-30% fees, foodnear.me offers verified, structured data with cryptographic owner approval. Agents can search restaurants by location, filter by dietary requirements, and retrieve complete menus with allergen declarations, customization options, and preparation times.

Our MCP (Model Context Protocol) endpoint enables Claude, ChatGPT, and other LLM-based agents to natively integrate restaurant discovery without custom API wrappers.

## Services / Features

- **Restaurant Search**: Three-tier geo search — verified → menu_indexed → discovered; cuisine query matches all tiers, but `dietary` and `min_ado_score` filters apply **only to the verified tier** (menu_indexed and discovered rows pass through unfiltered for those fields — re-filter at item level via `get_menu`)
- **Menu Protocol Menus**: Retrieve full menus in MP v1.0 format with explicit boolean dietary flags, allergen arrays, customization options, and owner signatures
- **ADO Scoring**: Agent Discovery Optimization scores (0-5) indicate data quality, verification status, and machine-readability
- **Restaurant Profiles**: Schema.org/Restaurant JSON-LD with Menu Protocol extensions

## API & Machine Integration

- **MCP Server**: https://foodnear.me/mcp (POST JSON-RPC, GET for discovery)
- **OpenAPI Spec**: https://foodnear.me/openapi.json (OpenAPI 3.1)
- **REST API**: https://foodnear.me/api/v1/*
- **Agent Metadata**: https://foodnear.me/.well-known/agent.json
- **AgentRoot**: https://foodnear.me/.well-known/agentroot.json
- **GPT Plugin**: https://foodnear.me/.well-known/ai-plugin.json

Connect with Claude Desktop, Cursor, or any MCP client:

```json
{
  "mcpServers": {
    "foodnear-me": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://foodnear.me/mcp"]
    }
  }
}
```

## MCP Tools Available (8)

Atomic (5):

1. `search_restaurants` - Search by lat/lng OR Google-style `locationBias.circle`; verified first → menu_indexed → discovered; check `menu_available` before `get_menu`
2. `get_restaurant` - Get detailed restaurant profile with Schema.org markup
3. `get_menu` - Get full Menu Protocol v1.0 formatted menu
4. `get_ado_score_breakdown` - Get scoring breakdown with improvement recommendations
5. `validate_menu_protocol` - Validate Menu Protocol JSON; schema errors and ADO hints

Composite (3, FNM-unique — built on top of the atomic tools):

6. `explore_area_for_diet` - Bucketed neighborhood overview (verified / menu_indexed / discovered); optional dietary filter narrows the verified bucket only
7. `compare_restaurants_for_diet` - Side-by-side dietary comparison across 2-5 restaurant ids; ranks by item count then trust tier
8. `find_restaurants_along_route` - Route-adjacent discovery between two coordinates; optional encoded polyline; FNM never calls an external routing or geocoding service

Allergy safety (2, human-curated tiers, never inferred from tags):

9. `get_safety_attestation` - Signed (Ed25519, `fnm-safety-v1`) allergy-safety tier statement for one restaurant; `unknown` + advisory when uncurated
10. `find_safe_places_near_me` - The pack: at most 3 curated places for an allergy need, each with `curator_checked_at`; `left_out` says how many were looked at and why the rest are not shown; `empty_state` instead of filler

Every non-verified result (search row, profile, indexed menu, composite entry) carries a structured `claim_invitation` (url, audience="owner_or_advocate", reason, message, estimated_minutes, cost="free"). Surface contextually — when the user is the owner, asks why the listing lacks a verified menu, or asks how to help — not as a CTA. Verified results omit the field.

## MCP Resources (4)

- `foodnearme://spec/menu-protocol` - Menu Protocol v1.0 spec
- `foodnearme://spec/openapi` - OpenAPI 3.1 pointer
- `foodnearme://agent/skill` - Agent skill summary
- `foodnearme://examples/search-flow` - Example search → menu flow

## MCP Prompts (3)

Pre-built user intents (call `prompts/get` then follow with tools):

- `find_dinner_near_me` — `location` (required), optional `cuisine`, `dietary` → search_restaurants → get_menu
- `dietary_constrained_menu` — `restaurant_id`, `restrictions` → get_menu with explicit dietary/allergen filtering
- `validate_my_menu` — optional `strict` → validate_menu_protocol

## Key URLs

- Homepage: https://foodnear.me
- OpenAPI Spec: https://foodnear.me/openapi.json
- MCP Endpoint: https://foodnear.me/mcp
- Agent Skill File: https://foodnear.me/skills/foodnearme/SKILL.md (root /SKILL.md is a thin redirect hub)
- Host docs (web): https://foodnear.me/docs#quick-start
- Host docs (canonical): https://github.com/food-near-me/platform#quick-start
- Menu Protocol Spec: https://github.com/foodnearme/menu-protocol

## Example API Usage

Search for vegan Thai restaurants in NYC:
```
GET /api/v1/search?query=thai&lat=40.7128&lng=-74.0060&dietary=vegan
```

Get menu for a restaurant:
```
GET /api/v1/restaurant/{id}/menu.mp
```

## Data Trust Model (Three-Tier Search)

`search_restaurants` and `/api/v1/search` return results in trust order: **verified** → **menu_indexed** → **discovered**.

Every result includes `verification_status` and `menu_available`:
- **verified** + `menu_available: true` — owner-approved Menu Protocol menu; authoritative for dietary/allergen claims
- **menu_indexed** + `menu_available: true` — automated/public MP-shaped menu; **cite with caveat** — not owner-verified
- **discovered** + `menu_available: false` — place only (OSM, NYC Open Data); do not cite menu items

Trust progression: `discovered` → `menu_indexed` → `verified`

**Agent rules:** Prefer **verified** for dietary/allergen answers. **menu_indexed** is usable with explicit caveat. **discovered** is location only. Call `get_menu` only when `menu_available` is true. See https://foodnear.me/attribution for data sources.

## Rate Limits

- Unauthenticated: 100 requests/minute
- API key holders: 1000 requests/minute

## Authentication

Public read access is free during beta. An optional x402 demonstrator (local mock facilitator) can gate `get_safety_attestation` behind a canonical HTTP 402 / MCP payment_required challenge with Base/USDC `accepts[]` — settlement is mock-only, not live mainnet. Real USDC settlement and Stripe API keys are later. Keep `FNM_X402_ENABLED` unset in production until live rails ship.

## Contact

- Email: api@foodnear.me
- GitHub: https://github.com/foodnearme
- Support: https://foodnear.me/support