Indian–American Diaspora MCP Server

Agent-first, agent-only data layer for the Indian-American diaspora. Phase 1: Indian restaurants (USA). This repo is the walking skeleton from the architecture blueprint:

• MCP server exposing restaurant capabilities (get_indian_restaurants, get_restaurant_details, search_restaurants_by_text, find_unclaimed_restaurants, draft_claim_outreach, submit_correction), temple capabilities (get_indian_temples, get_temple_details, search_temples_by_text) and grocery capabilities (get_indian_groceries, get_grocery_details, search_groceries_by_text) professional capabilities (get_indian_professionals, …), salon capabilities (get_indian_salons, …), and a cross-vertical search_all that searches every vertical at once (each result tagged with its vertical).
• Data pipeline: scrape → raw → clean/enrich/score → approval queue → canonical table → versioning.
• One real scraper: OpenStreetMap Overpass (public, ODbL-licensed, no login, ToS-safe).
• Storage: PostgreSQL (+ pgvector for future embedding search) via Docker Compose.

Connect (live MCP server)

The hosted server is remote (no install) over streamable‑HTTP:

• Endpoint: https://namasteamerica.us/mcp (transport: streamable-http, auth: none, read‑only)
• Descriptor: https://namasteamerica.us/.well-known/mcp.json · Docs: https://namasteamerica.us/for-agents

{ "mcpServers": { "namaste-america": { "type": "streamable-http", "url": "https://namasteamerica.us/mcp" } } }

Tools (per vertical: restaurants, temples, groceries, professionals, salons, events, apparel, sweets, studios, services, community, legal, education, real estate, finance): get_indian_<category>, search_<category>_by_text, get_<category>_details, and a cross‑vertical search_all. Each result is JSON with address, geo, hours, contact, ratings, and languages.

Publishing to the official MCP registry: the manifest is server.json (namespace us.namasteamerica, verified via DNS). Install the CLI (mcp-publisher), authenticate the domain (mcp-publisher login dns --domain namasteamerica.us, then add the TXT record it prints), and run mcp-publisher publish.

Architecture (Phase 1)

 OSM Overpass ──▶ restaurant_raw ──▶ clean()+score() ──▶ approval_queue ──▶ restaurants
   (scraper)        (JSONB)            (pipeline)         (high-risk only)   (canonical)
                                                                                 │
                                                                                 ▼
                                                                        restaurant_versions
                                                                                 │
                                                                                 ▼
                                                                     MCP tools (FastMCP)

Low-risk new inserts are auto-applied (configurable); updates to claimed/featured listings are routed to the human approval queue.

Quick start

Requires Docker Desktop and Python 3.11+.

# 1. Start Postgres (with pgvector)
docker compose up -d

# 2. Create a virtualenv and install
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

# 3. Configure env
copy .env.example .env   # default DATABASE_URL already points at the docker container

# 4. Initialise the schema
python -m indo_usa_mcp.cli init-db

# 5. Scrape one metro from OpenStreetMap, then process raw -> canonical
python -m indo_usa_mcp.cli scrape --metro bay_area
python -m indo_usa_mcp.cli process

# 6. Inspect
python -m indo_usa_mcp.cli stats

# 7. Run the MCP server (stdio transport)
python -m indo_usa_mcp.server

CLI

Monetization & delivery

• Featured listings (feature/unfeature) — a paid tier; effectively-featured rows (flagged and within their featured_until window) surface first in every tool result.
• Stripe checkout (optional) — claimed owners get a "Get Featured" button → Stripe Checkout → a signature-verified webhook (/stripe/webhook) auto-features them. Disabled until STRIPE_SECRET_KEY is set (then it's pay-per-sale, no monthly fee). See DEPLOY.md.
• Outreach email delivery — optional and zero-cost: set Gmail SMTP + an app password in .env (see .env.example) and the Outreach Agent will auto-send claim emails to restaurants that have a public email; otherwise it stays draft-only.
• Enrichment agent — strengthens the cultural "data moat" by inferring region/dietary tags from restaurant names (free, keyword-based).

Coverage spans 15 metros (Bay Area, NYC/NJ, Dallas, Houston, Chicago, LA, Seattle, Atlanta, Phoenix, Austin, Boston, Philadelphia, Raleigh, Detroit, Central NJ) plus an on-demand nationwide sweep (scrape --metro usa).

WhatsApp outreach is delivered as free click-to-send wa.me links (message pre-filled); true auto-send WhatsApp needs a paid API and is intentionally not used.

Trying it without a live scrape

python -m indo_usa_mcp.cli init-db
python -m indo_usa_mcp.cli seed     # 12 fictional restaurants across the 5 metros
python -m indo_usa_mcp.cli stats

Then exercise the MCP tools (e.g. get_indian_restaurants near the Bay Area, or search_restaurants_by_text "vegetarian dosa").

Search quality (for LLM agents)

Records are optimized for agent retrieval:

• Natural-language description per record (e.g. "Saffron House is a Gujarati Indian restaurant in Edison, NJ. Offers vegetarian, jain options. Price: $$.") — generated from the structured fields, returned to agents, and used as the text that gets embedded.
• Reverse-geocoded location — missing city/state are filled offline from coordinates (reverse_geocoder), so "near me / in " queries work for every record.
• Keyword + attribute tags (e.g. biryani, dosa, halal, delivery, takeout, outdoor-seating, wheelchair-accessible, wifi, cards-accepted, organic) — derived from names and rich OSM attributes; agents filter with tag=..., and they boost embedding recall + appear in the description ("Amenities: …").
• open_now — opening_hours are parsed into structured per-day intervals; each result carries an open_now flag (true/false/null) and the tools accept an open_now=true filter, enabling "what's open near me right now".
• Dedup-merge — the admin Quality view lists duplicate groups with a one-click merge (fills the keeper's empty fields, soft-deletes the rest).

search_*_by_text ranks by embedding cosine distance (pgvector <=>), falling back to trigram. Providers (EMBEDDING_PROVIDER):

• hashing (default) — feature-hashing, zero extra deps; lexical.
• fastembed (recommended, prod default) — real semantic embeddings via BAAI/bge-small-en-v1.5 (384-dim, ONNX, no torch). The Docker image includes it and the prod compose defaults EMBEDDING_PROVIDER=fastembed; after deploying run python -m indo_usa_mcp.cli enhance-data once to re-embed existing rows. Set EMBEDDING_PROVIDER=hashing if the VPS is RAM-constrained.
• sentence_transformers — all-MiniLM-L6-v2 (heavier, pulls torch).
• none — trigram only.

enhance-data (re)generates descriptions, fills geocoding, and re-embeds existing rows — run it after enabling a new embedder. New records get all of this automatically on ingest.

Outreach & claiming (blueprint §7)

# Draft claim messages + single-use claim links for unclaimed restaurants
python -m indo_usa_mcp.cli outreach --limit 10

# Later, an owner verifies their claim token (normally via the claim web page)
python -m indo_usa_mcp.cli verify-claim <token> --email owner@example.com

After claiming, owners get an edit page (/manage?token=...) to update their phone, hours, menu, price, dietary tags, etc. — changes go live immediately and are protected from scraper overwrites (scraper updates to claimed listings route to the approval queue). Stale listings not re-seen for 60 days are auto-deactivated (is_active=false) and reactivated if they reappear in a later scrape.