io.github.jeeva-m-21Published by GitHub account jeeva-m-21v2.0.0Updated Oct 27, 2026
Hyperlocal commerce and verified merchant directory MCP server for Chennai, India.
The publisher's own server: ShopFront Locations
Remote MCP server for a verified Chennai merchant directory that lets an assistant find local shops, read their catalogs and hours, and produce WhatsApp or…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.jeeva-m-21%2Fshopfront/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"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)Source: README.md at commit 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_slugrequiredRetrieve available menu or service catalog items for a shop grouped by category, with price display and duration, supporting cursor-based pagination.
kindcursorshop_slugrequiredSearch items within a specific shop catalog using text similarity and full-text search with optional price ceiling and item kind filtering.
kindlimitqueryrequiredshop_slugrequiredmax_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_slugrequiredcustomer_notepreferred_time90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare a license in the repository or the registry entry.
┌────────────────────────────────────────────────────────────────────────┐│ 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