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