Commerce Price MCP

A TypeScript MCP server for comparing Indian quick-commerce and e-commerce product prices.

What it does

• Searches configured marketplace adapters in parallel.

• Normalizes listings into one schema.

• Ranks by landed price = item price + known delivery fee.

• Returns direct product links supplied by each connector.

• Persists every observed price to data/history.jsonl.

• Exposes price history.

• Predicts 15-30 day direction using an explainable daily-minimum trend + EWMA model.

• Provides a best_buy_decision tool.

Marketplace connector slots: blinkit, zepto, instamart, bigbasket, jiomart, amazon_in, flipkart.

Why connectors are separated

Retailers differ materially in authentication, location handling, public API access, anti-bot controls, and terms. Do not hard-code brittle page scraping into the MCP core.

Each non-core connector can be:

1. an official retailer/affiliate API,

2. an official MCP,

3. a licensed commerce-data provider,

4. your own compliant browser service.

The MCP never needs to change when a provider changes.

Current Swiggy/Instamart path

Swiggy publishes an Instamart MCP at:

https://mcp.swiggy.com/im

It uses OAuth 2.1 with PKCE. For production, either:

• connect your app directly to that MCP and expose its search_products result through a small HTTP bridge matching the adapter contract below, or

• extend this project with @modelcontextprotocol/client and an OAuth token provider.

A bridge is intentionally not bundled here because OAuth is user/session-specific.

Adapter contract

Configure each *_ADAPTER_URL. The MCP sends:

{
  "query": "Aashirvaad Shudh Chakki Atta",
  "pincode": "751019",
  "quantity": 5,
  "unit": "kg",
  "limit": 10
}

Your provider should return:

{
  "items": [
    {
      "title": "Aashirvaad Shudh Chakki Atta 5 kg",
      "price": 249,
      "mrp": 300,
      "deliveryFee": 0,
      "url": "https://...",
      "inStock": true,
      "quantity": 5,
      "unit": "kg",
      "productId": "..."
    }
  ]
}

platform is optional because the adapter injects it.

Install

Requires Node.js 20+.

npm install
cp .env.example .env
# Fill adapter URLs, then export them or load them with your process manager.
npm run dev

Test with MCP Inspector:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

MCP tools

list_marketplaces

Shows supported and currently configured connectors.

search_product

Input:

• query

• pincode

• optional exact quantity and unit

• optional platform filter

Output:

• lowest

• all normalized results sorted by landed price

• direct URLs

• connector errors without failing the entire search

get_price_history

Takes canonicalKey, days, and optional pincode.

predict_price

Takes canonicalKey, horizonDays (15-30), optional pincode.

At least 3 distinct historical days are required; 14+ is recommended. Confidence is based on observation count and regression noise.

best_buy_decision

Searches now and combines the current lowest listing with available history:

• rising forecast -> buy_now

• falling forecast -> consider_waiting

• stable -> neutral

• too little history -> insufficient_history

Important matching rule

"Lowest price" is dangerous unless pack sizes are matched. Pass quantity + unit whenever possible. The server also emits matchScore; for production, improve this with GTIN/EAN/UPC identifiers and retailer product IDs.

Production upgrades I recommend

1. PostgreSQL/TimescaleDB instead of JSONL.

2. GTIN/EAN-based product entity resolution.

3. Location-aware taxes, fees, membership pricing, coupons, and minimum-cart rules.

4. Scheduled snapshots (e.g. 2-4/day) so history is real history, not only user searches.

5. Festival/calendar/promotion features for the forecast.

6. Per-marketplace rate limits, retries, cache, circuit breakers and observability.

7. A separate "same product confidence" model to prevent false cheapest matches.

8. Store both base price and checkout-effective price; do not mix them.

9. Backtest forecasts (MAE/MAPE/directional accuracy) before displaying confidence.

10. Respect each provider's terms, robots/automation policy, authentication and rate limits.

Example host configuration

For a local stdio MCP host, configure a command equivalent to:

{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/commerce-price-mcp/src/index.ts"],
  "env": {
    "BLINKIT_ADAPTER_URL": "https://your-provider/blinkit/search",
    "ZEPTO_ADAPTER_URL": "https://your-provider/zepto/search"
  }
}

Forecast caveat

A 15-30 day retail-price forecast is inherently uncertain. Promotions, inventory, seller changes, festival sales, memberships and location can dominate the signal. Treat the forecast as a decision aid, not as a guaranteed future price.