Shopfront MCP server
Commit Oct 18, 2026Enables AI assistants to discover, query, and recommend verified local merchants and real-time product availability in Chennai, India.
Also known as jeeva-m-21/shopfront, shopfront
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- ā
- Latest version
- 2.0.0
- Last commit
- Oct 18, 2026
- License
- ā
What is Shopfront MCP?
Shopfront enables AI assistants to discover, query, and recommend verified local merchants and real-time product availability in Chennai, India. It exposes 5 tools, such as find_shops, get_shop_info, get_catalog.
Summary generated from the project's README
About Shopfront MCP server
Helping AI assistants discover and recommend verified local merchants in Chennai is what Shopfront enables. It bridges the gap between physical urban retail and conversational intelligence by turning neighborhood shops into queryable nodes. This allows users to ask questions about specific products, prices, and real-time availability directly within their preferred AI tools.
Developers and businesses use this server by connecting it to clients like Claude Desktop, Cursor, or custom agent sidecars via a streamable HTTP MCP endpoint. The system relies on a PostgreSQL 16 and PostGIS 3.4 backend to provide precise spatial indexing and sub-25ms retrieval. It is designed to prevent the hallucinations common in LLMs by providing ground truth data regarding operating hours, exact rupee pricing, and live stock status.
Merchants maintain control through a mobile-first portal where they can manage discrete shift intervals, toggle item availability with a single tap, and set up direct WhatsApp connections. This setup avoids the high commissions of traditional aggregators while ensuring AI assistants receive authenticated, real-time information.
Written from the project's README. Every use case is checked against a quote from it.
How to install Shopfront MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Shopfront MCP in Claude Code
$ claude mcp add --transport http shopfront https://shopfront-rouge.vercel.app/mcpInstall Shopfront MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"shopfront": {
"url": "https://shopfront-rouge.vercel.app/mcp"
}
}
}Install Shopfront MCP in VS Code
.vscode/mcp.json
{
"servers": {
"shopfront": {
"type": "http",
"url": "https://shopfront-rouge.vercel.app/mcp"
}
}
}Install Shopfront MCP in VS Code CLI
$ code --add-mcp '{"name":"shopfront","type":"http","url":"https://shopfront-rouge.vercel.app/mcp"}'Install Shopfront MCP in Codex
$ codex mcp add shopfront --url https://shopfront-rouge.vercel.app/mcpInstall Shopfront MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.shopfront] url = "https://shopfront-rouge.vercel.app/mcp"
Install Shopfront MCP in Gemini CLI
$ gemini mcp add -s user --transport http shopfront https://shopfront-rouge.vercel.app/mcpInstall Shopfront MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"shopfront": {
"url": "https://shopfront-rouge.vercel.app/mcp",
"type": "http"
}
}
}Shopfront MCP tools 5
Detected from the READMEfind_shopsget_shop_infoget_catalogsearch_catalogget_action_link
| find_shops | ā | |
| get_shop_info | ā | |
| get_catalog | ā | |
| search_catalog | ā | |
| get_action_link | ā |
Configuration
APP_BASE_URLDATABASE_URLRERANK_ENABLEDSTAGE1_TIMEOUT_MS
| Name | Description | |
|---|---|---|
| APP_BASE_URL | ā | |
| DATABASE_URL | ā | |
| RERANK_ENABLED | ā | |
| STAGE1_TIMEOUT_MS | ā |
Automated checks
Ran Nov 14, 2026Full report āNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work Ā· What to fix for more points
- Source repository linked and reachablejeeva-m-21/shopfront is public and reachablegithub.com/jeeva-m-21/shopfront āPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-18github.com/jeeva-m-21/shopfront āPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 388 msPass
README
View on GitHubšŖ Shopfront: Local Shops, Found by AI
āBe the answer when people ask AI.ā
Shopfront makes local businesses visible to AI assistants through the open Model Context Protocol (MCP).
ā” Quick Links & Live Demos
| Resource | Direct Link | Description |
|---|---|---|
| š Live Web Application | shopfront-rouge.vercel.app | Real-time discovery portal with verified Chennai merchant ledgers. |
| š¤ AI Agent Connect Portal | shopfront-rouge.vercel.app/connect | 60-second MCP setup for Claude Desktop, Cursor, and custom agent sidecars. |
| šØ Brand & Vector Assets | shopfront-rouge.vercel.app/brand | Official Stitch multi-view SVG logo system, typography, and color tokens. |
| š Technical Architecture Case Study | TECHNICAL_CASE_STUDY.md |
Exhaustive problem-to-solution system design, PostGIS spatial indexing, and security architecture. |
| š Streamable HTTP MCP Endpoint | POST https://shopfront-rouge.vercel.app/api/mcp |
RFC-compliant Model Context Protocol streamable transport for agents. |
š Table of Contents
- The Core Novelty & Positioning
- The Breakdown of Urban Apps vs. The AI Shift
- The Solution: Three Key Differentiators
- Deep Customization: You Decide What AI Says
- System Architecture & Request Lifecycle
- Live Endpoints & Model Context Protocol (MCP) Tools
- Connect to AI Assistants (Claude, Cursor, ChatGPT)
- Design System: "The Shutter Goes Up"
- Scientific Offline Evaluation & Benchmarks
- Local Development & Test Gates
1. The Core Novelty & Positioning
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.ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā 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 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.
2. The Breakdown of Urban Apps vs. The AI Shift
Urban commerce is experiencing a structural paradigm shift driven by consumer app fatigue and conversational 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
The Three Critical Industry Breakdown Points:
- App Fatigue: Customers do not want to download, register, and update 30 different mobile apps for every local bakery, barber, and motorcycle garage.
- The Aggregator Tax: Conventional aggregators extract 20% to 30% of gross transaction volume and mask customer identities, preventing merchants from building long-term loyalty.
- The AI Search Blind Spot: When consumers ask Claude, Cursor, or ChatGPT for local recommendations, LLMs hallucinate or return generic blog scrapes because brick-and-mortar stores have no standard API or protocol representation.
3. The Solution: Three Key Differentiators
Shopfront replaces the fragmented app nightmare with a unified, protocol-driven architecture:
| Differentiator | Traditional Aggregators & Franchise Apps | Shopfront (MCP Engine) |
|---|---|---|
| 1. AI-Native Protocol | ā Walled gardens; closed to AI assistants; invisible to conversational search. | ā Native Model Context Protocol (MCP) server readable by Claude, Cursor, ChatGPT, and custom agent sidecars. |
| 2. One Listing vs. 20 Apps | ā Merchants spend ā¹1,50,000+ building custom apps that users immediately uninstall. | ā One low-cost, commission-free listing that automatically syndicates across all AI assistants. |
| 3. Owner-Controlled Direct Contact | ā Masked phone numbers; platform lock-in; delayed weekly payouts. | ā Direct WhatsApp & telephone connection with pre-filled enquiry templates. Merchants keep 100% of revenue. |
4. Deep Customization: You Decide What AI Says
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:
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
The 8 Signature Customization Levers:
- 1. Operating Shifts & Lunch Breaks: Configure discrete shift intervals (e.g. 09:00ā13:00 and 16:30ā21:30) and upcoming holiday dates. AI never sends customers to a closed shutter.
- 2. Exact Rupee Pricing: List precise prices (e.g. iPhone Battery: ā¹1,800) to qualify high-intent customers and eliminate haggling.
- 3. Instant Availability Toggle: Flip an item unavailable with a single thumb-tap from your phone when parts run out. AI updates immediately.
- 4. Spatial Service Area: Pinpoint exact physical coordinates and service radiuses in PostGIS (SRID 4326).
- 5. Authentic Brand Story: Provide background on your techniques, heritage, and quality guarantees for AI to champion.
- 6. Pre-Formatted WhatsApp Message: Customize the greeting message generated when customers click your action link.
- 7. Bilingual Tamil & English Support: Enable native Tamil script matching alongside standard English.
- 8. Persistent "AI Preview": A live dashboard card in the Owner Portal showing the exact conversational response and raw MCP JSON that AI assistants receive.
5. System Architecture & Request Lifecycle
Shopfront combines sub-25ms PostGIS SQL retrieval with an LLM semantic decision reranker and a fail-open circuit breaker.
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. Live Endpoints & Model Context Protocol (MCP) Tools
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).
Official MCP Registry Listing:
io.github.jeeva-m-21/shopfront
The 5 Core MCP Tools:
| Tool Name | Parameters | Description |
|---|---|---|
find_shops |
category?, locality?, latitude?, longitude?, radius_km?, query?, max_price_inr?, open_now? |
Discovers and ranks Chennai shops matching physical, budget, and operational constraints. |
get_shop_info |
shop_id or slug |
Retrieves complete shop profile, physical address, locality coordinates, weekly operating shifts, and upcoming 30-day closures. |
get_catalog |
shop_id, cursor?, limit? |
Fetches available menu offerings and service rates grouped by section with keyset pagination. |
search_catalog |
shop_id, query, kind?, max_price_inr?, limit? |
Executes text similarity search within a specific shop's catalog. |
get_action_link |
shop_id, item_id?, item_name? |
Generates verified WhatsApp deep-link (wa.me) or telephone link with pre-formatted enquiry message and disclaimer. |
7. Connect to AI Assistants (Claude, Cursor, ChatGPT)
You can connect Shopfront to your AI assistant in under 60 seconds.
Option A: Claude Desktop (Local Stdio)
Add Shopfront to your 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"
}
}
}
}
Option B: Remote Streamable HTTP (Cursor / Web Agents)
In Cursor (Settings $\rightarrow$ Features $\rightarrow$ MCP Servers):
- Type:
commandorsse/streamable-http - URL:
https://shopfront-rouge.vercel.app/api/mcp
8. Design System: "The Shutter Goes Up"
The brand identity avoids generic SaaS gradients in favor of an authentic Chennai visual identity rooted in physical urban commerce: the rolling metal shop shutter.
| Master View | Asset Preview | Spec |
|---|---|---|
| 01 / Primary Horizontal | 4:1 Lockup on Light Surface | |
| 02 / Brand Hero | High-contrast on Marina Teal (#0E6B66) |
|
| 03 / Stacked Emblem | 1:1 Square Splash Emblem | |
| 06 / App Icon Squircles | 80Ć80 Squircle ($r = 25%$) |
- Marina Teal (
#0E6B66): Inspired by Marina Beach at dusk. Primary buttons, active indicators, and focus rings. - Motion Turmeric (
#F4B000): Single focal accent per screen. Used for the lifted top slat and live verified badges. - Stone Neutrals (
#FAF9F6to#100F0D): Warm paper-and-ink gray tones. - Explore All Assets: Visit shopfront-rouge.vercel.app/brand to download standalone SVGs.
9. Scientific Offline Evaluation & Benchmarks
Shopfront incorporates a rigorous offline evaluation framework executing 40 golden benchmark queries (30 Dev, 10 Held-out) across 4 query topologies:
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā 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 ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāā
Read the full engineering deep dive in
TECHNICAL_CASE_STUDY.md.
10. Local Development & Test Gates
Prerequisites
- Node.js 22+ (pinned via
.nvmrc) - PostgreSQL 16 with PostGIS 3.4 extension
- Docker & Docker Compose (optional for local DB)
Setup & Run
# 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
Shopfront MCP questions
How do I add Shopfront MCP to Claude Code?
Run claude mcp add --transport http shopfront https://shopfront-rouge.vercel.app/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Shopfront MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Shopfront MCP provide?
It exposes 5 tools, including find_shops, get_shop_info, get_catalog, search_catalog, get_action_link.
How does Shopfront help local businesses?
It makes local businesses visible to AI assistants, allowing them to be found by users asking conversational questions instead of using traditional apps.
Can merchants control what information the AI provides?
Yes, owners use a mobile-first portal to manage operating hours, exact pricing, live item availability, and service areas.
How do customers contact the shops found by the AI?
The AI provides direct WhatsApp and telephone connections with pre-filled enquiry templates.
What technologies power the search retrieval?
The system uses PostGIS for spatial indexing and a two-stage retrieval pipeline including an LLM semantic decision reranker.