io.github.jeeva-m-21由 GitHub 帳號 jeeva-m-21 發布v2.0.0更新於 Oct 27, 2026
Hyperlocal commerce and verified merchant directory MCP server for Chennai, India.
發布方自己的服務：ShopFront Locations
針對清奈在地商家目錄的遠端 MCP 伺服器，讓助理查找店家、讀取菜單與營業時間，並產生 WhatsApp 或電話聯絡連結。
Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。
把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。
閱讀 https://sourceweft.com/mcp/io.github.jeeva-m-21%2Fshopfront/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。把它新增到你客戶端的 mcpServers 設定中。
{
"mcpServers": {
"shopfront-chennai-local-commerce": {
"type": "http",
"url": "https://shopfront-rouge.vercel.app/mcp"
}
}
}“Be the answer when people ask AI.”
Shopfront makes local businesses visible to AI assistants through the open Model Context Protocol (MCP).
[Production Status] [MCP Registry] [Technical Case Study] [Test Gates] [Playwright E2E]
[TypeScript 5.8] [Next.js 15] [PostgreSQL 16 / PostGIS 3.4] [Tailwind CSS v4] [Docker Ready] [Zero ORM] [License: MIT]
One line: Shopfront makes local businesses visible to AI assistants.
Tagline: “Be the answer when people ask AI.”
Short form: “Local shops, found by AI.”
Shopfront bridges the gap between physical urban retail and conversational intelligence. By turning neighborhood shops into queryable, authenticated nodes on the Model Context Protocol (MCP), merchants gain direct customer inquiries without building custom mobile apps or forfeiting 30% aggregator commissions.
Urban commerce is experiencing a structural paradigm shift driven by consumer app fatigue and conversational AI:
Shopfront replaces the fragmented app nightmare with a unified, protocol-driven architecture:
Shopfront provides local merchants with absolute sovereignty over their data. Through the mobile-first Owner Portal, owners decide exactly what AI assistants know and recommend:
Shopfront combines sub-25ms PostGIS SQL retrieval with an LLM semantic decision reranker and a fail-open circuit breaker.
Shopfront implements the Model Context Protocol (MCP 1.32.1) specification over Web Standard Streamable HTTP (POST /api/mcp) and local Stdio (scripts/mcp-stdio.ts).
You can connect Shopfront to your AI assistant in under 60 seconds.
Add Shopfront to your claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonIn Cursor (Settings $\rightarrow$ Features $\rightarrow$ MCP Servers):
command or sse / streamable-httphttps://shopfront-rouge.vercel.app/api/mcpThe brand identity avoids generic SaaS gradients in favor of an authentic Chennai visual identity rooted in physical urban commerce: the rolling metal shop shutter.
#0E6B66): Inspired by Marina Beach at dusk. Primary buttons, active indicators, and focus rings.#F4B000): Single focal accent per screen. Used for the lifted top slat and live verified badges.#FAF9F6 to #100F0D): Warm paper-and-ink gray tones.Shopfront incorporates a rigorous offline evaluation framework executing 40 golden benchmark queries (30 Dev, 10 Held-out) across 4 query topologies:
Read the full engineering deep dive in
TECHNICAL_CASE_STUDY.md.
.nvmrc)來源：README.md，提交 3dbddb4
Find and rank local shops in Chennai for a customer request. Always provide locality when the customer has told you where they are. If the customer has not said where they are, ask them for a Chennai area before calling this tool. Use category when it is clear. Results already satisfy distance, budget, and open-now constraints.
latlnglimitquerycategorylocalityopen_nowradius_kmmax_price_inrRetrieve detailed public shop profile including address, locality, coordinates, weekly opening hours, upcoming closures, contact numbers, action mode, and latest menu timestamp.
shop_slug必填Retrieve available menu or service catalog items for a shop grouped by category, with price display and duration, supporting cursor-based pagination.
kindcursorshop_slug必填Search items within a specific shop catalog using text similarity and full-text search with optional price ceiling and item kind filtering.
kindlimitquery必填shop_slug必填max_price_inrGenerate an actionable WhatsApp deep link, booking URL, or phone dial link with standard customer enquiry message for a shop and optional item.
item_idshop_slug必填customer_notepreferred_time已滿足適用檢查項的 90%
該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。
請在儲存庫或註冊中心條目中宣告授權條款。
┌────────────────────────────────────────────────────────────────────────┐│ 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/..." │└────────────────────────────────────────────────────────────────────────┘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| Solutionmindmap 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 terminologyflowchart 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| Outputio.github.jeeva-m-21/shopfront{ "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" } } }}┌────────────────────────────────────────────────────────────────────────┐│ 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 │└────────────────────────────────┴───────────────┴───────────────────────┘# 1. Clone the repositorygit clone https://github.com/your-username/shopfront.gitcd shopfront
# 2. Install pinned dependenciesnpm ci
# 3. Environment configurationcp .env.example .env
# 4. Start PostGIS containerdocker-compose up -d db
# 5. Run database migrations & seed fixturesnpm run db:migratenpm run db:seed
# 6. Execute native check gates (40 suites, 234 tests)npm test
# 7. Execute Playwright E2E lifecycle testnpx playwright test
# 8. Run offline evaluation benchmarknpm run eval
# 9. Start development servernpm run dev