Namaste America

インド系アメリカ人ディアスポラ MCP サーバー

インド系アメリカ人ディアスポラ向けの、エージェントファーストでエージェント専用のデータレイヤーです。フェーズ 1：米国のインド料理レストラン。 このリポジトリは、アーキテクチャ設計図から作成された、動作する骨格です。

• レストラン機能（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 がタグ付けされています）を提供する MCP サーバー。
• データパイプライン：スクレイピング → raw → クリーンアップ／拡充／スコア付け → 承認キュー → 正規テーブル → バージョン管理。
• 実際に動作するスクレイパー 1 つ：OpenStreetMap Overpass（公開、ODbL ライセンス、ログイン不要、利用規約に準拠）。
• ストレージ：Docker Compose 経由の PostgreSQL（将来の埋め込み検索用に pgvector を使用）。

接続（稼働中の MCP サーバー）

ホストされているサーバーは、ストリーミング可能な 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 <name>	エージェントをすぐに1つ実行します（agent_runs に監査記録が残ります）。
agents-loop [--once]	スケジューラーを実行します（実行時刻になったエージェントをワーカーループで処理します）。
query [--city/--text/--lat --lng/--id/...]	ターミナルから MCP ツール関数を呼び出します。
seed	ローカルテスト用の架空のレストランデータを読み込みます（スクレイピングは不要です）。
enrich	タグ付けが不十分なレストランに、地域・食文化タグを補完します。
deactivate-stale [--days 60]	最近確認されていない未登録の掲載情報を非アクティブにします。
approval-digest	保留中の承認キューの内容を、人が読みやすい形式で要約します。
feedback --id N --field F --value V	フィールドの修正を送信します（フィードバックエージェントが適用します）。
scrape --metro usa	全米を対象にスイープを実行します（必要に応じて実施。単一都市圏より時間がかかります）。
feature --id N [--days 30 | --permanent]	有料の注目掲載として設定します。
unfeature --id N	注目掲載を解除します。
backfill-embeddings [--all]	正規化された行の埋め込みを再計算します。
stats	行数とカバレッジの概要を表示します。

収益化と配信

• 注目掲載（feature/unfeature） — 有料プランです。実際に注目掲載されている行（フラグが設定され、featured_until の期間内にあるもの）は、すべてのツールの結果で先頭に表示されます。
• Stripe チェックアウト（任意） — 登録済みのオーナーには「注目掲載を利用」ボタンが表示されます。ボタンから Stripe Checkout に進み、署名検証済みの Webhook（/stripe/webhook）によって自動的に注目掲載されます。STRIPE_SECRET_KEY が設定されるまで無効です（設定後は販売ごとの課金となり、月額料金はありません）。DEPLOY.md を参照してください。
• 案内メールの配信 — 任意で、無料です。.env に Gmail SMTP とアプリパスワードを設定すると（.env.example を参照）、案内エージェントが公開メールアドレスのあるレストランに登録案内メールを自動送信します。設定しない場合は下書きの作成のみ行います。
• エンリッチメントエージェント — レストラン名から地域・食文化タグを推定し、文化的な「データの堀」を強化します（無料、キーワードベース）。

対象範囲は15の都市圏（ベイエリア、NYC/NJ、ダラス、ヒューストン、シカゴ、LA、シアトル、アトランタ、フェニックス、オースティン、ボストン、フィラデルフィア、ローリー、デトロイト、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 エージェント向け）

レコードはエージェントが取得しやすいように最適化されています。

• レコードごとに自然言語の description（例：「Saffron House はニュージャージー州エジソンにあるグジャラート料理のインド料理店です。ベジタリアン料理とジャイナ教徒向けのメニューを提供しています。価格：$$。」）を用意しています。構造化フィールドから生成され、エージェントに返されるほか、埋め込みに使用されるテキストとしても使われます。
• 逆ジオコーディングされた所在地 — city／state がない場合は、座標を使ってオフラインで補完されるため（reverse_geocoder）、「近くの／にある」といったクエリがすべてのレコードで機能します。
• キーワードと属性の tags（例：biryani、dosa、halal、delivery、takeout、outdoor-seating、wheelchair-accessible、wifi、cards-accepted、organic）— 名前と詳細な OSM 属性から生成されます。エージェントは tag=... で絞り込み、埋め込み検索の再現率向上にも使われます。また、説明文（「設備：…」）にも表示されます。
• open_now — opening_hours は曜日ごとの構造化された時間帯に解析されます。各検索結果には open_now フラグ（true／false／null）が含まれ、ツールでは open_now=true で絞り込めるため、「今、近くで営業している店は？」という検索が可能です。
• 重複の統合 — 管理画面の品質ビューには、ワンクリックで統合できる重複グループが表示されます（残すレコードの空欄を補完し、それ以外はソフト削除します）。

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 の RAM が制約される場合は 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）、その後のスクレイピングで再び見つかった場合は再有効化されます。

アウトリーチエージェントは、未登録のレストランを見つけ（未解決の登録申請があるもの、または OUTREACH_COOLDOWN_DAYS 以内に連絡済みのものは除外します）、1 回限りの登録トークンとリンクを作成し、各レストラン向けに誠実で、配信停止にも配慮したメッセージの下書きを作成します。メッセージは自動送信されません。配信にはチャネル連携が必要で、チェーン店／注目店／価値の高い対象には requires_human のフラグが付けられます。オーナーが確認を完了すると、restaurants.is_claimed が true に切り替わり、そのリスティングへの今後のスクレイパー更新は承認キューに送られます。エージェントは find_unclaimed_restaurants および draft_claim_outreach MCP ツールを使ってこの処理を実行できます。

自律型エージェント（設計図 §6）

各エージェントはパイプラインのステップを実行し、冪等性を備え、完全な監査行を agent_runs に書き込みます（エラーは記録され、正規データが中途半端な状態で書き込まれることはありません）。

エージェント	内容
discovery	地域ごとのカバレッジを報告し、スクレイピング対象を提案します。
scraper	すべてのスクレイパーを各地域で実行し、restaurant_raw に取り込みます。
cleaner	raw データをクリーンアップ／スコアリング／承認処理を経て正規データに変換します。
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)

データソース

2つの独立した公開スクレイパーがパイプラインにデータを取り込みます。osm_overpass（OpenStreetMap、ODbL）と wikidata（Wikidata SPARQL、CC0）です。scrape --source <name> でどちらかを選択します。Scraper Agent は両方を実行します。

フェーズ 2：寺院の垂直領域

同じパイプライン、エージェント、埋め込み、デプロイを共有する独立した垂直領域（ヒンドゥー教／シク教／ジャイナ教の礼拝所）です。これはブループリントの「独立した垂直領域、共有インフラ」という原則に沿っています。独自のテーブル（temples）、独自の OSM スクレイパー（amenity=place_of_worship + religion）、独自のエージェント（temple_scraper、temple_cleaner）、独自の MCP ツールを備えています。文化的な情報補完では、名前から神格（Venkateswara、Krishna、Lakshmi…）と地域（シク教なら Punjabi、Swaminarayan なら Gujarati、Venkateswara なら Telugu…）を推定します。

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…）、独自のエージェント（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"

管理ダッシュボード、レポート、オーナーポータル

ウェブアプリ（:8080）は、現在 3 種類の利用者に対応しています。

• 一般利用者／オーナー — /、/claim、/manage、/upgrade（既存）
• 管理者（/admin/*、パスワード保護）— 概要 KPI、垂直領域を横断するデータ管理 （閲覧／検索／編集／注目表示／無効化／論理削除）、地理情報のドリルダウン （国 → 州 → 都市。クリックするとレコードを絞り込み）、品質管理（地域／連絡先／位置情報／都市が 欠落しているレコードと重複グループを表示。ワンクリックで都市／州を標準化）、 承認とフィードバックのキュー、エージェント（最終実行時の状態、即時実行、アラート解決）、 トラフィック（すべての MCP ツール呼び出しを記録：ツール別／エージェント・クライアント別／日別、および 最も多く表示された掲載情報）、決済、レポート。有効にするにはADMIN_PASSWORDを設定します。空欄の場合は無効になります。
• オーナーは、ポータルで各掲載情報のリーチ数を確認できます（掲載情報ごとのインプレッション追跡に基づく「AI アシスタントによる表示回数 N 回」）。注目掲載の販売につなげる具体的な手がかりになります。
• 顧客ポータル（/portal/*）— オーナーはメールのパスワードレス・マジックリンクでサインインし、すべての垂直領域にわたる掲載情報を管理できます（編集、注目ステータス、アップグレード）。

日次レポート：reportingエージェントは毎晩、健全性と成長のスナップショットを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テーブル、スクレイパー、エージェント（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：サロンの垂直領域（美容／スレッディング）

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：イベント分野（自動化、管理者承認）

インド系アメリカ人コミュニティのイベント（祭り、ガルバ、コンサート、プージャ）。完全に自動化されており、エージェントがデータベースに登録済みの団体のウェブサイト（まずは寺院）をスキャンしてカレンダーリンクを探し、iCal フィードを自動検出します。エージェントはこれらのフィードと 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、blueprint §10）

ホスト環境の全スタック（Postgres + MCP サーバー（HTTP）+ エージェントワーカー）は、 docker-compose.prod.yml に記載されています。

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

• server はマイグレーション（冪等）を実行してから、:8000 で streamable-http 経由の MCP を提供します。
• worker はエージェントのスケジューラー（スクレイピング → クリーンアップ → 監視 …）を実行します。起動前にスキーマが準備されるのを待つため、サービスの起動順序は問いません。
• 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 は実装済みで、スキーマ + バージョン管理 + 承認キュー、パイプライン、2 つのスクレイパー（OSM + Wikidata）、5 つすべての MCP ツール、セマンティック検索（pgvector）、アウトリーチと登録申請、スケジューラー付きの 6 つの自律エージェント、シードフィクスチャ、ホスト環境へのデプロイスタックがエンドツーエンドで稼働しています。残る「最後の仕上げ」は、実際のアウトリーチチャネルへの配信、登録申請用ウェブページ、Approval-Assistant + Feedback エージェント、収益化ロジック、本番環境向けの強化（HTTPS、バックアップ）です。今後追加する各分野（寺院、イベント、食料品店など）には、それぞれ専用のテーブル／スクレイパー／ツールを用意しつつ、インフラは共有します。