Namaste America

印度裔美国人社群 MCP 服务

面向 Agent、仅供 Agent 使用的印度裔美国人社群数据层。第 1 阶段：美国的印度餐厅。 本仓库是架构蓝图中的基础骨架：

• MCP 服务提供餐厅功能（get_indian_restaurants、 get_restaurant_details、search_restaurants_by_text、find_unclaimed_restaurants、 draft_claim_outreach、submit_correction）、寺庙功能 （get_indian_temples、get_temple_details、search_temples_by_text）和杂货店 功能（get_indian_groceries、get_grocery_details、search_groceries_by_text）， 专业人士功能（get_indian_professionals，……）、沙龙功能 （get_indian_salons，……），以及可一次搜索所有垂直领域的跨领域 search_all （每条结果都带有其 vertical 标签）。
• 数据管道：抓取 → 原始数据 → 清理／丰富／评分 → 审批队列 → 规范表 → 版本管理。
• 一个实际抓取器：OpenStreetMap Overpass（公开、采用 ODbL 许可、无需登录，且符合服务条款）。
• 存储：通过 Docker Compose 使用 PostgreSQL（未来用于向量嵌入搜索的 pgvector）。

连接（在线 MCP 服务）

托管服务通过 streamable‑HTTP 提供远程访问（无需安装）：

• 端点： https://namasteamerica.us/mcp（传输方式：streamable-http，认证：无，只读）
• 描述文件： https://namasteamerica.us/.well-known/mcp.json · 文档： https://namasteamerica.us/for-agents

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

工具（按垂直领域划分：餐厅、寺庙、杂货店、专业人士、沙龙、活动、服饰、甜品、工作室、服务、社群、法律、教育、房地产、金融）： get_indian_<category>、search_<category>_by_text、get_<category>_details，以及跨领域 search_all。每条结果均为 JSON，包含地址、地理位置、营业时间、联系方式、评分和语言。

发布到官方 MCP 注册表：清单文件为 server.json（命名空间 us.namasteamerica，通过 DNS 验证）。安装 CLI（mcp-publisher），验证域名 （mcp-publisher login dns --domain namasteamerica.us，然后添加它输出的 TXT 记录），并运行 mcp-publisher publish。

架构（第 1 阶段）

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

低风险的新建条目会自动应用（可配置）；对已认领／精选列表的更新 会转交人工审批队列。

快速开始

需要 Docker Desktop 和 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

命令	用途
init-db	应用 SQL 迁移（扩展、表、索引）。
scrape --metro <name>	将 OSM 抓取器运行于某个都市圈的 bbox，并写入 restaurant_raw。
process	清理并评分尚未处理的原始行；自动应用低风险项，将高风险项加入队列。
approvals	列出待处理的审批队列项目。
approve <id> / reject <id>	处理一项审批。
outreach [--limit N]	为尚未认领的餐厅起草认领联系信息（创建认领链接和消息）。
verify-claim <token>	餐厅所有者端：验证认领令牌并取得所有权。
agents	列出已注册的自主 Agent。
agent <name>	立即运行一个 Agent（记录在 agent_runs 中）。
agents-loop [--once]	运行调度器（循环处理到期 Agent）。
query [--city/--text/--lat --lng/--id/...]	在终端中调用 MCP 工具函数。
seed	加载虚构的种子餐厅以供本地测试（无需抓取）。
enrich	为标签不足的餐厅补充地区和饮食文化标签。
deactivate-stale [--days 60]	将近期未出现的未认领餐厅列表标记为不活跃。
approval-digest	以易读的形式汇总待处理的审批队列。
feedback --id N --field F --value V	提交字段修正（由反馈 Agent 应用）。
scrape --metro usa	全国范围扫描（偶尔运行；比单个都市圈扫描慢）。
feature --id N [--days 30 | --permanent]	标记付费精选列表。
unfeature --id N	移除精选列表标记。
backfill-embeddings [--all]	为规范行（重新）计算嵌入向量。
stats	行数和覆盖范围摘要。

变现与交付

• 精选列表（feature/unfeature）——付费层级；实际获得精选资格的行（已标记且处于 featured_until 有效期内）会优先显示在每个工具结果中。
• Stripe 结账（可选）——已认领餐厅的所有者可点击“Get Featured”按钮 → Stripe 结账 → 通过签名验证的 webhook（/stripe/webhook）自动将其设为精选。设置 STRIPE_SECRET_KEY 后才会启用（届时按次收费，不收月费）。参见 DEPLOY.md。
• 外联邮件发送——可选且免费：在 .env 中设置 Gmail SMTP 和应用专用密码（参见 .env.example），外联 Agent 就会自动向有公开邮箱的餐厅发送认领邮件；否则仅保存为草稿。
• 数据丰富 Agent——根据餐厅名称推断地区和饮食标签，强化文化“数据护城河”（免费，基于关键词）。

覆盖范围包括 15 个都市圈（湾区、NYC/NJ、Dallas、Houston、Chicago、LA、Seattle、Atlanta、Phoenix、Austin、Boston、Philadelphia、Raleigh、Detroit、Central NJ），另有按需运行的全国范围扫描（scrape --metro usa）。

WhatsApp 外联通过免费的点击发送 wa.me 链接交付（预填消息）；WhatsApp 自动发送需要付费 API，因此有意不使用。

无需实时抓取即可试用

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

然后试用 MCP 工具（例如，获取湾区附近的 get_indian_restaurants，或运行 search_restaurants_by_text "vegetarian dosa"）。

搜索质量（适用于 LLM Agent）

记录针对 Agent 检索进行了优化：

• 每条记录都包含自然语言 description（例如 “Saffron House 是位于新泽西州 Edison 的古吉拉特印度餐厅，提供素食和耆那教餐食选择。价格：$$。”）——根据结构化字段生成，返回给 Agent，并作为用于生成嵌入的文本。
• 反向地理编码的位置——根据坐标离线填充缺失的 city/state（reverse_geocoder），因此“我附近 / 的”查询适用于每条记录。
• 关键词和属性 tags（例如 biryani、dosa、halal、delivery、takeout、outdoor-seating、wheelchair-accessible、wifi、cards-accepted、organic）——根据名称和丰富的 OSM 属性生成；Agent 使用 tag=... 筛选，也能借此提升嵌入召回率，并在描述中显示（“设施：……”）。
• open_now——将 opening_hours 解析为按星期划分的结构化时段；每条结果都带有 open_now 标志（true/false/null），工具支持 open_now=true 筛选，从而支持“现在我附近有哪些店营业”这类查询。
• 去重合并——管理后台的 Quality 视图会列出重复记录组，并提供一键合并功能（填充保留记录的空字段，并软删除其余记录）。

search_*_by_text 按嵌入余弦距离（pgvector <=>）排序，必要时回退到三元组匹配。提供方（EMBEDDING_PROVIDER）：

• hashing（默认）——特征哈希，无额外依赖；基于词汇匹配。
• fastembed（推荐，生产环境默认值）——通过 BAAI/bge-small-en-v1.5 提供真正的语义嵌入（384 维、ONNX、无需 torch）。Docker 镜像已包含该模型，生产环境的 compose 默认使用 EMBEDDING_PROVIDER=fastembed；部署后运行一次 python -m indo_usa_mcp.cli enhance-data，为现有行重新生成嵌入。如果 VPS 内存受限，请设置 EMBEDDING_PROVIDER=hashing。
• sentence_transformers——all-MiniLM-L6-v2（体积较大，会下载 torch）。
• none——仅使用三元组匹配。

enhance-data 会（重新）生成描述、填充地理编码，并为现有行重新生成嵌入——启用新的嵌入器后请运行此命令。摄取新记录时会自动完成上述所有操作。

外联与认领（蓝图 §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 [email protected]

认领后，所有者会获得一个编辑页面（/manage?token=...），可在其中更新电话、营业时间、菜单、价格、饮食标签等——更改会立即生效，并受到保护，不会被抓取器覆盖（抓取器对已认领商家信息的更新会进入审批队列）。 过期商家信息若连续 60 天未再次出现，会自动停用（is_active=false）；如果之后的抓取中重新出现，则会重新激活。

外联 Agent 会查找未认领的餐厅（跳过任何存在待处理认领或在 OUTREACH_COOLDOWN_DAYS 天内已联系过的餐厅），创建一次性认领令牌和链接，并为每家餐厅拟定诚恳、便于选择退出的消息。消息不会自动发送——投递需要集成相应渠道；连锁店、精选餐厅和高价值目标会标记为 requires_human。所有者完成验证后，restaurants.is_claimed 会变为 true，之后抓取器对该商家信息的更新都会进入审批队列。Agent 可通过 find_unclaimed_restaurants 和 draft_claim_outreach MCP 工具执行这些操作。

自主 Agent（蓝图 §6）

每个 Agent 都封装一个管线步骤，具备幂等性，并向 agent_runs 写入完整的审计记录（捕获错误，不会只写入一部分规范数据）。

Agent	功能
discovery	报告都市圈覆盖情况并提出抓取目标。
scraper	在每个都市圈运行所有抓取器，将结果写入 restaurant_raw。
cleaner	通过清理/评分/审批，将原始数据处理为规范数据。
outreach	为符合条件的未认领餐厅拟定认领外联消息。
monitoring	检测异常（积压、抓取器故障、数据过期）并写入 agent_alerts。
submission	将 MCP 提交至目录（目前为手动存根）。

python -m indo_usa_mcp.cli agents              # list agents
python -m indo_usa_mcp.cli agent scraper       # run one, audited
python -m indo_usa_mcp.cli agents-loop --once  # one scheduler pass (scrape→clean→monitor…)
python -m indo_usa_mcp.agents.scheduler        # long-lived scheduler (VPS worker)

数据源

两个独立的公开抓取器为此流水线提供数据：osm_overpass（OpenStreetMap，ODbL） 和 wikidata（Wikidata SPARQL，CC0）。使用 scrape --source <name> 选择其一；Scraper Agent 会运行两者。

第 2 阶段：寺庙垂直领域

一个独立的垂直领域（印度教／锡克教／耆那教礼拜场所），与其他领域共用同一条流水线、 Agent、嵌入和部署——遵循蓝图中的“垂直领域独立，基础设施共享”原则。使用独立的表 （temples）、独立的 OSM 抓取器（amenity=place_of_worship + religion）、 独立的 Agent（temple_scraper、temple_cleaner）和 MCP 工具。文化信息增强功能会根据名称推断神祇（Venkateswara、Krishna、Lakshmi……）和地区（锡克教对应旁遮普语、Swaminarayan 对应古吉拉特语、Venkateswara 对应泰卢固语……）。

python -m indo_usa_mcp.cli temples-scrape --metro bay_area
python -m indo_usa_mcp.cli temples-process
python -m indo_usa_mcp.cli temples-stats
python -m indo_usa_mcp.cli temples-query --religion hindu --city Fremont
python -m indo_usa_mcp.cli temples-query --text "swaminarayan gujarati mandir"

第 2 阶段：杂货店垂直领域

采用与寺庙相同的方案——独立的 groceries 表 + OSM 抓取器（名称表明销售印度杂货的杂货店，例如 Patel、India、Apna、Swad、Masala……）+ 独立的 Agent （grocery_scraper、grocery_cleaner）+ 3 个 MCP 工具。推断 store_type 和 region_tag。

python -m indo_usa_mcp.cli groceries-scrape --metro bay_area
python -m indo_usa_mcp.cli groceries-process
python -m indo_usa_mcp.cli groceries-query --city Fremont
python -m indo_usa_mcp.cli groceries-query --text "patel brothers indian grocery"

管理仪表板、报告与商家门户

Web 应用（:8080）现在面向三类用户：

• 公众／商家 — /、/claim、/manage、/upgrade（已有功能）
• 管理员（/admin/*，由密码保护）— 概览 KPI、跨垂直领域的数据控制（浏览／搜索／编辑／设为精选／停用／软删除）、地理信息下钻（国家 → 州 → 城市，点击即可筛选记录）、质量控制（标记缺少地区／联系方式／地理位置／城市信息的记录及重复组，并提供一键式城市／州规范化工具）、审批与反馈队列、Agent（最近运行状态、立即运行、处理提醒）、流量（记录每次 MCP 工具调用：按工具／Agent 客户端／日期统计，并显示曝光次数最多的商家信息）、付款和报告。设置 ADMIN_PASSWORD 以启用；留空则禁用。
• 商家可在门户中查看每条商家信息的触达量（“被 AI 助手展示 N 次”，数据来自逐条商家信息的展示次数跟踪）——这是销售精选展示位的直接依据。
• 客户门户（/portal/*）— 商家通过无密码的魔法链接邮件登录，并管理其在各垂直领域的所有商家信息（编辑、精选状态、升级）。

每日报告：reporting Agent 每晚将健康状况与增长快照写入 daily_reports，在 /admin/reports 中展示，并通过 SMTP 发送至 REPORT_EMAIL。 使用 python -m indo_usa_mcp.cli report 可按需运行。

安全：公开 /admin 前，请启用 HTTPS（Caddy 的 tls 配置文件），并设置强密码 ADMIN_PASSWORD 和 随机的 SECRET_KEY。

第 2 阶段：专业人士垂直领域（医生／医疗健康）

面向印度裔美国医疗健康专业人士——医生、牙医、诊所、药房——通过 OSM 医疗设施 及印度姓名特征（姓氏／阿育吠陀）查找。采用与其他垂直领域相同的方案：独立的 professionals 表、抓取器、Agent（professional_scraper、 professional_cleaner）、3 个 MCP 工具，以及 profession_type／speciality 筛选器。 由于姓名匹配基于启发式规则，每条记录都带有 confidence_score，管理员可通过“质量” 视图筛选并整理误报记录。

python -m indo_usa_mcp.cli professionals-scrape --metro bay_area
python -m indo_usa_mcp.cli professionals-process
python -m indo_usa_mcp.cli professionals-query --type dentist --city "San Jose"

第 2 阶段：美容沙龙垂直领域（美容／穿线脱毛）

印度美容沙龙——眉毛穿线脱毛、海娜／mehndi、理发、新娘妆——通过 OSM 美发／美容店铺及明显的南亚服务／名称特征查找。采用相同方案；标签记录服务 （穿线脱毛、海娜、新娘妆……）。目前在各垂直领域中，该领域的 OSM 覆盖率最高。

python -m indo_usa_mcp.cli salons-scrape --metro bay_area
python -m indo_usa_mcp.cli salons-process
python -m indo_usa_mcp.cli salons-query --tag threading --city Sunnyvale

阶段 2：活动垂直领域（自动化，经管理员批准）

印度裔美国人社区活动（节庆、garba、音乐会、puja）。完全自动化—— Agent 会扫描数据库中已有组织（首先是寺庙）的网站，自动发现 iCal 订阅源，并且 Agent 会从这些订阅源以及 EVENT_ICAL_FEEDS 中的任何订阅源导入活动。清理器会自动批准高置信度活动，并将其余活动加入队列，供管理员在 Admin → Events 中一键批准（无需手动录入）。过去的活动会保留，不会删除——它们会通过日期筛选从即将举行的活动结果中排除（get_indian_events 默认返回即将举行的活动；include_past=true 可查询历史），并通过 18 个月的保留策略清除非常久远的活动。

python -m indo_usa_mcp.cli events-discover     # scan org websites for iCal feeds
python -m indo_usa_mcp.cli events-scrape      # ingest configured + discovered iCal feeds
python -m indo_usa_mcp.cli events-process     # auto-approve / queue for admin
python -m indo_usa_mcp.cli events-approvals   # list pending
python -m indo_usa_mcp.cli events-query --city Edison --category garba

连接 MCP 客户端

将任意 MCP 客户端（Claude Desktop 等）指向：

{
  "mcpServers": {
    "indo-usa-diaspora": {
      "command": "python",
      "args": ["-m", "indo_usa_mcp.server"],
      "env": { "DATABASE_URL": "postgresql://diaspora:diaspora@localhost:5433/diaspora" }
    }
  }
}

部署（VPS，蓝图 §10）

完整的托管技术栈——Postgres + MCP 服务（HTTP）+ Agent worker——位于 docker-compose.prod.yml：

$env:POSTGRES_PASSWORD = "choose-a-strong-password"
docker compose -f docker-compose.prod.yml up -d --build

• server 会运行迁移（幂等），然后通过 streamable-http 在 :8000 提供 MCP 服务。
• worker 会运行 Agent 调度器（抓取 → 清理 → 监控……）；它会等待架构就绪后再启动，因此服务启动顺序无关紧要。
• db 保持在内部网络中（不对外发布）。

在 :8000 前配置一个负责 TLS 终止的反向代理（Caddy/nginx/Traefik）以启用 HTTPS， 并添加防火墙和定时 pg_dump 备份。MCP 端点为 https://<host>/mcp。

使用 MCP Inspector 检查

以标准的可视化方式调用这些工具：

# stdio (local)
npx @modelcontextprotocol/inspector .\.venv\Scripts\python.exe -m indo_usa_mcp.server

# or point the Inspector at a running HTTP server: http://localhost:8000/mcp

遵循的防护措施

• 仅使用公开数据（OSM/ODbL），不抓取需要登录的数据，不处理个人数据，并限制请求速率。
• 置信度评分、软删除、完整版本历史。
• 高风险更新需人工批准；is_featured 是明确且可见的标记。

状态 / 路线图

阶段 1 已实现并端到端运行：架构 + 版本管理 + 审批队列、流水线、两个抓取器（OSM + Wikidata）、全部 5 个 MCP 工具、语义（pgvector）搜索、推广联系与认领、六个自主 Agent 及其调度器、种子数据 fixture，以及托管部署技术栈。剩余的“最后一公里”工作：实际发送推广联系信息、认领网页、Approval-Assistant + Feedback Agent、变现逻辑，以及生产环境加固（HTTPS、备份）。每个未来的垂直领域（寺庙、活动、杂货店……）都有自己的表、抓取器和工具，但共享这套基础设施。