Shopfront Chennai Local Commerce

🏪 Shopfront：本地商店，由 AI 发现

“让 AI 在回答问题时推荐你。”
Shopfront 通过开放的 Model Context Protocol（MCP），让本地商家更容易被 AI 助手发现。

---

---

⚡ 快速链接与在线演示

资源	直接链接	说明
🌐 在线 Web 应用	shopfront-rouge.vercel.app	实时发现门户，提供经核实的金奈商家名录。
🤖 AI Agent 连接门户	shopfront-rouge.vercel.app/connect	60 秒即可为 Claude Desktop、Cursor 和自定义 Agent 侧车完成 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 可流式传输传输方式，供 Agent 使用。

---

📋 目录

1. 核心创新与定位
2. 城市应用的衰落与 AI 转型
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

行业面临的三个关键问题：

1. 应用疲劳： 顾客不想为每一家本地面包店、理发店和摩托车修理店分别下载、注册和更新 30 个不同的移动应用。
2. 聚合平台税： 传统聚合平台抽取 20% 至 30% 的交易总额，并隐藏客户身份，使商家无法建立长期忠诚度。
3. AI 搜索盲区： 消费者向 Claude、Cursor 或 ChatGPT 询问本地推荐时，由于实体店没有标准 API 或协议表示，大模型会产生幻觉，或返回从博客抓取的泛泛内容。

---

3. 解决方案：三大关键优势

Shopfront 以统一的协议驱动架构，取代支离破碎的应用困局：

优势	传统聚合平台与连锁品牌应用	Shopfront（MCP 引擎）
1. 原生适配 AI 的协议	❌ 封闭生态；不向 AI 助手开放；在对话式搜索中不可见。	✅ 原生 Model Context Protocol（MCP） 服务，可供 Claude、Cursor、ChatGPT 和自定义 Agent sidecar 读取。
2. 一个商家页面，胜过 20 个应用	❌ 商家花费 ₹1,50,000+ 开发定制应用，用户却会立即卸载。	✅ 一个低成本、免佣金的商家页面，自动同步至所有 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

八项特色自定义功能：

• 1. 营业班次与午休时间： 配置不同时段的营业时间（例如 09:00–13:00 和 16:30–21:30）及即将到来的节假日。AI 不会把顾客带到已经关门的店铺。
• 2. 精确的卢比定价： 列出准确价格（例如 iPhone 电池：₹1,800），吸引意向明确的客户，避免讨价还价。
• 3. 即时库存状态切换： 当零件售罄时，只需在手机上轻点一下即可将商品标记为缺货。AI 会立即更新。
• 4. 空间服务范围： 在 PostGIS（SRID 4326）中标记精确的地理坐标和服务半径。
• 5. 真实的品牌故事： 介绍你的技艺、传承和质量保证，让 AI 可以重点推荐。
• 6. 预设 WhatsApp 消息： 自定义顾客点击操作链接时生成的问候消息。
• 7. 泰米尔语与英语双语支持： 支持泰米尔语原生文字匹配，同时兼容标准英语。
• 8. 持续更新的“AI 预览”： 商家门户中的实时仪表盘卡片，展示 AI 助手收到的确切对话回复和原始 MCP JSON。

---

5. 系统架构与请求生命周期

Shopfront 将低于 25 毫秒的 PostGIS SQL 检索与大模型语义决策重排序器相结合，并配备故障时默认放行的断路器。

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 Registry 条目：

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）

不到 60 秒，即可将 Shopfront 连接到 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 Agent）

在 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）： 每个屏幕仅使用一个视觉焦点色。用于抬起的顶层门片和实时验证徽章。
• 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 固定版本）
• PostgreSQL 16 和 PostGIS 3.4 扩展
• Docker 与 Docker Compose（本地数据库可选）

安装与运行

# 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

---