Shopfront Chennai Local Commerce

🏪 Shopfront：AIが見つける地元のお店

「AIに質問されたとき、答えとして選ばれましょう。」
Shopfrontは、オープンなModel Context Protocol（MCP）を通じて、地域のビジネスをAIアシスタントから見つけられるようにします。

---

---

⚡ クイックリンクとライブデモ

リソース	直接リンク	説明
🌐 ライブWebアプリケーション	shopfront-rouge.vercel.app	チェンナイの認証済み店舗台帳を備えたリアルタイム検索ポータルです。
🤖 AIエージェント接続ポータル	shopfront-rouge.vercel.app/connect	Claude Desktop、Cursor、カスタムエージェントサイドカー向けの60秒で完了するMCPセットアップです。
🎨 ブランドとベクター素材	shopfront-rouge.vercel.app/brand	Stitch公式の多視点SVGロゴシステム、タイポグラフィ、カラートークンです。
📖 技術アーキテクチャのケーススタディ	TECHNICAL_CASE_STUDY.md	課題から解決策までの包括的なシステム設計、PostGIS空間インデックス、セキュリティアーキテクチャを解説します。
🔌 ストリーミング可能なHTTP MCPエンドポイント	POST https://shopfront-rouge.vercel.app/api/mcp	エージェント向けのRFC準拠Model Context Protocolストリーミングトランスポートです。

---

📋 目次

1. 中核となる新規性と位置付け
2. 都市型アプリの課題とAIへの移行
3. ソリューション：3つの主な差別化要因
4. 高度なカスタマイズ：AIの回答を自分で決める
5. システムアーキテクチャとリクエストのライフサイクル
6. ライブエンドポイントとModel Context Protocol（MCP）ツール
7. AIアシスタント（Claude、Cursor、ChatGPT）に接続する
8. デザインシステム：「シャッターが上がる」
9. 科学的なオフライン評価とベンチマーク
10. ローカル開発とテストゲート

---

1. 中核となる新規性と位置付け

一言で言うと： Shopfront は、AI アシスタントが地域のビジネスを見つけられるようにします。
タグライン： 「AI に聞かれたとき、答えとして選ばれましょう。」
短縮形： 「AI が見つける地域のお店。」

┌────────────────────────────────────────────────────────────────────────┐
│  CUSTOMER ASKS AI:                                                     │
│  "Where can I get my iPhone battery replaced in Adyar right now under  │
│   ₹2,000?"                                                             │
├────────────────────────────────────────────────────────────────────────┤
│  WITHOUT SHOPFRONT:                                                    │
│  ❌ "I don't have real-time access to local shops or current prices.  │
│      You may want to check Google Maps or call nearby stores."         │
├────────────────────────────────────────────────────────────────────────┤
│  WITH SHOPFRONT (MCP):                                                 │
│  ✅ "I found A1 Electronics in Adyar (450m away). They are open right  │
│      now (verified 9m ago). Their iPhone Battery Replacement is        │
│      ₹1,800. Click here to chat with the owner on WhatsApp: wa.me/..." │
└────────────────────────────────────────────────────────────────────────┘

Shopfront は、実店舗の都市型小売と会話型インテリジェンスの間にあるギャップを埋めます。近隣の店舗を Model Context Protocol（MCP）上で検索可能かつ認証されたノードに変えることで、加盟店は独自のモバイルアプリを構築したり、アグリゲーターに売上の30％を手数料として支払ったりすることなく、顧客から直接問い合わせを受けられます。

---

2. 都市型アプリの行き詰まりと AI への移行

消費者のアプリ疲れと会話型 AI を背景に、都市型商業は構造的なパラダイムシフトを迎えています。

flowchart TD
    subgraph TheAppTrap["The Separate Franchise App & Marketplace Trap"]
        A1["Separate App per Franchise<br/>(McDonald's app, Domino's app, Swiggy, Zomato, Urban Company)"]
        A2["Severe App Fatigue<br/>(Users delete single-use apps; refuse to install 30 separate apps)"]
        A3["20% to 30% Aggregator Commissions<br/>(High take-rates erode independent merchant margins)"]
        A4["Walled-Garden Data Silos<br/>(Customer phone numbers masked; zero direct relationship)"]
        A1 --> A2 --> A3 --> A4
    end

    subgraph TheAIShift["The Conversational AI Revolution"]
        B1["Users Ask AI Instead of Opening Apps<br/>('Find me a MacBook technician near Adyar')"]
        B2["AI Assistants Get ZERO Data<br/>(LLMs cannot read fragmented closed apps)"]
        B3["Result: Hallucinated defunct numbers or dead ends"]
        B1 --> B2 --> B3
    end

    TheAppTrap -.->|Broken Paradigm| Solution["Shopfront: The Authoritative Live Layer"]
    TheAIShift -.->|Needs Ground Truth| Solution

業界を行き詰まらせる3つの重大な要因：

1. アプリ疲れ： 顧客は、地域のパン屋や理髪店、バイク修理店ごとに、別々のモバイルアプリをダウンロードして、登録し、更新したいとは思っていません。
2. アグリゲーター税： 従来のアグリゲーターは、取引総額の20％から30％を徴収し、顧客の身元を隠すため、加盟店は長期的な顧客ロイヤルティを築けません。
3. AI 検索の盲点： 消費者が Claude、Cursor、ChatGPT に地域のおすすめを尋ねても、実店舗には標準的な API やプロトコルによる表現がないため、LLM は幻覚を起こしたり、一般的なブログ記事の寄せ集めを返したりします。

---

3. ソリューション：3つの主な差別化要因

Shopfront は、断片化したアプリの煩わしさを、統一されたプロトコル駆動型アーキテクチャで解消します。

差別化要因	従来のアグリゲーターとフランチャイズアプリ	Shopfront（MCP エンジン）
1. AI ネイティブなプロトコル	❌ 囲い込み型のサービスで、AI アシスタントには開かれておらず、会話型検索から見つけられません。	✅ Claude、Cursor、ChatGPT、カスタムのエージェントサイドカーが読み取れる、ネイティブな Model Context Protocol（MCP） サーバーです。
2. 20個のアプリではなく、1つの掲載情報	❌ 加盟店は、ユーザーがすぐにアンインストールする独自アプリの構築に₹1,50,000以上を費やします。	✅ 低コストで手数料のかからない1件の掲載情報が、すべての AI アシスタントに自動的に配信されます。
3. オーナーが管理する直接連絡	❌ 電話番号は隠され、プラットフォームに囲い込まれ、支払いは週単位で遅れて行われます。	✅ 定型の問い合わせメッセージを用いたWhatsApp と電話での直接連絡が可能です。加盟店は収益の100％を受け取れます。

---

4. 詳細なカスタマイズ：AI の回答を決めるのはあなたです

Shopfront は、地域の加盟店が自らのデータを完全に管理できるようにします。モバイルファーストのオーナーポータルから、オーナーは AI アシスタントが知る内容やおすすめする内容を正確に決められます。

mindmap
  root((Owner Customization))
    Hours & Shift Breaks
      Real-time IST schedule
      Afternoon lunch breaks
      Temple & festival closures
    Exact Rupee Pricing
      Fixed menu prices
      Transparent price ranges
      Warranty terms
    Live Availability
      1-thumb out-of-stock switches
      Capacity limits
    Service Area & Coordinates
      Millimeter PostGIS location
      Locality bounding polygon
    Craftsmanship & Story
      20+ years experience
      Specialist certifications
    WhatsApp Opening Template
      Pre-filled item context
      Direct wa.me deep links
    Bilingual Localization
      Tamil keywords ஷாப்ஃபிரண்ட்
      English terminology

カスタマイズできる8つの項目：

• 1. 営業シフトと昼休み： 具体的なシフト時間（例：09:00–13:00、16:30–21:30）と今後の休業日を設定できます。AI が、シャッターの閉まった店に顧客を案内することはありません。
• 2. 正確なルピー価格： 正確な価格（例：iPhone Battery：₹1,800）を掲載して、購入意欲の高い顧客を獲得し、値切り交渉をなくせます。
• 3. 即時の在庫状況切り替え： 部品がなくなったら、スマートフォンから親指でワンタップするだけで、商品を在庫切れにできます。AI に即座に反映されます。
• 4. 空間的なサービスエリア： PostGIS（SRID 4326）で、正確な物理座標とサービス提供半径を指定できます。
• 5. 真摯なブランドストーリー： 技法、伝統、品質保証について説明し、AI がそれを魅力として伝えられるようにします。
• 6. 定型 WhatsApp メッセージ： 顧客がアクションリンクをクリックした際に生成される挨拶メッセージをカスタマイズできます。
• 7. タミル語と英語のバイリンガル対応： 標準的な英語に加えて、タミル語のネイティブな文字列照合を有効にできます。
• 8. 常時表示の「AI プレビュー」： オーナーポータルのライブダッシュボードカードに、AI アシスタントが受け取る会話形式の応答と MCP の生 JSON が正確に表示されます。

---

5. システムアーキテクチャとリクエストのライフサイクル

Shopfront は、25ミリ秒未満の PostGIS SQL 検索と、LLM によるセマンティックな判断の再ランキング、さらにフェイルオープンのサーキットブレーカーを組み合わせています。

flowchart TB
    subgraph Ingress["1. Ingress Layer"]
        User["🌐 Customer Browser<br/>Next.js 15 App"]
        Agent["🤖 AI Agent (Claude Desktop)<br/>Streamable HTTP / Stdio"]
        Merchant["📱 Shop Owner<br/>Mobile Web Portal"]
    end

    subgraph SecurityLayer["2. Gateway Security & Auth"]
        RateLimit["⏱️ Sliding Window Rate Limiter<br/>(60 req/min)"]
        CSRF["🛡️ CSRF & Origin Guard<br/>(Sec-Fetch-Site Check)"]
        Argon["🔐 Argon2id (m=64MB, t=3, p=1)<br/>SHA-256 Session Token Hash"]
    end

    subgraph SearchPipeline["3. Two-Stage Retrieval Pipeline"]
        Stage1["⚡ Stage 1: PostGIS Fast SQL<br/>• Spatial Radius & Bounding Box (H1)<br/>• Live Status & Admin Lock Checks (H2)<br/>• IST Temporal Shift Matching (H6)<br/>• Statement Timeout: 250ms"]
        
        Sanitizer["🧹 Prompt Injection Stripper<br/>• Strip ASCII Control Chars<br/>• Exclude GPS coords, prices, hours"]
        
        Stage2["🧠 Stage 2: Jev Decisions LLM Reranker<br/>• Parallel Candidate Scoring<br/>• Expected Score E[score] Formulation<br/>• Strict Time Budget: min(timeout, rem-30ms)"]
        
        FailOpen["⚡ Fail-Open Circuit Breaker<br/>(On timeout/fault -> Fallback to Stage 1)"]
    end

    subgraph Storage["4. Authoritative Database (PostgreSQL 16 + PostGIS 3.4)"]
        PGPool["🐘 Dedicated Connection Pool (Zero ORM)"]
        Shops[("shops & localities<br/>Spatial GIST Index")]
        Catalog[("catalog_items<br/>Available Offerings")]
        Shifts[("operating_shifts<br/>IST Intervals")]
    end

    User --> RateLimit --> Stage1
    Agent --> RateLimit --> Stage1
    Merchant --> CSRF --> Argon --> PGPool

    Stage1 --> PGPool
    PGPool --> Shops
    PGPool --> Catalog
    PGPool --> Shifts

    Stage1 -->|Top 10 Candidates| Sanitizer
    Sanitizer --> Stage2
    Stage2 -.->|Timeout / Error| FailOpen
    FailOpen --> Output["📱 Verified WhatsApp Action Link"]
    Stage2 -->|Reranked Output| Output

---

6. ライブエンドポイントとModel Context Protocol（MCP）ツール

Shopfront は、Web Standard Streamable HTTP（POST /api/mcp）およびローカル Stdio（scripts/mcp-stdio.ts）を介して、**Model Context Protocol（MCP 1.32.1）**仕様を実装しています。

公式 MCP レジストリの掲載情報：

io.github.jeeva-m-21/shopfront

5 つのコア MCP ツール：

ツール名	パラメーター	説明
find_shops	category?、locality?、latitude?、longitude?、radius_km?、query?、max_price_inr?、open_now?	物理的な条件、予算、営業状況の制約に一致する Chennai の店舗を検索し、順位付けします。
get_shop_info	shop_id または slug	店舗の完全なプロフィール、住所、地域の座標、週間の営業時間、および今後 30 日間の休業日を取得します。
get_catalog	shop_id、cursor?、limit?	利用可能なメニューとサービス料金をセクションごとにまとめ、キーセットページネーションを使用して取得します。
search_catalog	shop_id、query、kind?、max_price_inr?、limit?	特定の店舗のカタログ内でテキスト類似度検索を実行します。
get_action_link	shop_id、item_id?、item_name?	問い合わせ文と免責事項をあらかじめ入力した、検証済みの WhatsApp ディープリンク（wa.me）または電話リンクを生成します。

---

7. AI アシスタントに接続する（Claude、Cursor、ChatGPT）

Shopfront は 60 秒以内に AI アシスタントへ接続できます。

オプション A：Claude Desktop（ローカル Stdio）

Shopfront を claude_desktop_config.json に追加します：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shopfront": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "/absolute/path/to/shopfront/scripts/mcp-stdio.ts"
      ],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5434/shopfront",
        "APP_BASE_URL": "https://shopfront-rouge.vercel.app",
        "STAGE1_TIMEOUT_MS": "250",
        "RERANK_ENABLED": "false"
      }
    }
  }
}

オプション B：リモート Streamable HTTP（Cursor／Web エージェント）

Cursor の（Settings $\rightarrow$ Features $\rightarrow$ MCP Servers）で設定します：

• タイプ： command または sse／streamable-http
• URL： https://shopfront-rouge.vercel.app/api/mcp

---

8. デザインシステム：「シャッターが上がる」

このブランドのアイデンティティでは、ありきたりな SaaS のグラデーションを避け、実店舗が並ぶ都市型商業に根ざした Chennai らしいビジュアルを採用しています。モチーフは巻き上げ式の金属製店舗シャッターです。

• Marina Teal（#0E6B66）： 夕暮れ時の Marina Beach をイメージしています。プライマリボタン、アクティブインジケーター、フォーカスリングに使用します。
• Motion Turmeric（#F4B000）： 画面ごとに 1 つのアクセントとして使用します。持ち上がった最上段のスラットと、リアルタイムの検証済みバッジに使います。
• Stone Neutrals（#FAF9F6 から #100F0D）： 温かみのある紙とインクを思わせるグレー系の色調です。
• すべてのアセットを見る： shopfront-rouge.vercel.app/brand にアクセスして、個別の SVG をダウンロードしてください。

---

9. 科学的なオフライン評価とベンチマーク

Shopfront には、4 つのクエリトポロジーを対象とする 40 件のゴールデンベンチマーククエリ（開発用 30 件、保留用 10 件）を実行する、厳格なオフライン評価フレームワークが組み込まれています：

┌────────────────────────────────────────────────────────────────────────┐
│  OFFLINE EVALUATION HARNESS RESULTS (eval/results/latest-report.md)     │
├────────────────────────────────┬───────────────┬───────────────────────┤
│ Metric                         │ Stage 1 SQL   │ Stage 2 LLM Reranked  │
├────────────────────────────────┼───────────────┼───────────────────────┤
│ Overall NDCG@5                 │ 0.8853        │ 0.8873 (+0.0020)      │
│ Direct Service NDCG@5          │ 0.8379        │ 0.8423 (+0.0044)      │
│ Specificity NDCG@5             │ 0.9176        │ 0.9210 (+0.0034)      │
│ Overall MRR@5                  │ 0.8000        │ 0.8000                │
│ Overall Recall@10              │ 1.0000        │ 1.0000                │
│ Inter-Annotator Agreement      │ Cohen's κ = 0.864 (90.0% agreement)   │
│ Latency P50 / P95              │ 22.4 ms / 147 ms                      │
│ 95% Confidence Intervals       │ 10,000-sample Mulberry32 Bootstrap    │
└────────────────────────────────┴───────────────┴───────────────────────┘

TECHNICAL_CASE_STUDY.md で、エンジニアリングの詳細な解説をお読みください。

---

10. ローカル開発とテストゲート

前提条件

• Node.js 22 以降（.nvmrc で固定）
• PostGIS 3.4 拡張機能を備えた PostgreSQL 16
• Docker と Docker Compose（ローカル DB を使用する場合は任意）

セットアップと実行

# 1. Clone the repository
git clone https://github.com/your-username/shopfront.git
cd shopfront

# 2. Install pinned dependencies
npm ci

# 3. Environment configuration
cp .env.example .env

# 4. Start PostGIS container
docker-compose up -d db

# 5. Run database migrations & seed fixtures
npm run db:migrate
npm run db:seed

# 6. Execute native check gates (40 suites, 234 tests)
npm test

# 7. Execute Playwright E2E lifecycle test
npx playwright test

# 8. Run offline evaluation benchmark
npm run eval

# 9. Start development server
npm run dev

---