@laundromatic/shopgraph

Structured product data from the open web, where platform APIs don't reach. Schema.org + AI extraction. Pay per call via Stripe MPP.

Website: https://shopgraph.dev | MCP Endpoint: https://shopgraph.dev/mcp

What it does

Agents connect via Model Context Protocol and call enrichment tools to extract structured product data from URLs. Requests are payment-gated via Stripe: unauthenticated calls receive a 402 challenge, authenticated calls with a payment_method_id are processed and billed.

Architecture

Agent → MCP (streamable-http) → enrich_product / enrich_basic
  → Cache hit? Return immediately (free)
  → No payment_method_id? Return 402 + MPP challenge
  → Payment confirmed → schema.org extraction (fast, 0.95 confidence)
  → No structured data? → Gemini LLM fallback (0.7+ confidence)
  → Bot-blocked or JS-rendered? → Playwright browser fallback
  → Return ProductData + PaymentReceipt

Setup

npm install

Required environment variables in .env:

Note: Check .env for duplicate key definitions — dotenv uses the last occurrence.

Build & Run

npm run build          # Compile TypeScript
npm start              # Run MCP server (stdio)
npm run start:http     # Run HTTP server (for Vercel/remote)
npm run dev            # Run with tsx (no build needed)

Test

npm run test:run       # Run all tests once
npm test               # Run tests in watch mode

Tools

Cached results are returned free of charge (24-hour TTL).

MCP Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "shopgraph": {
      "command": "node",
      "args": ["/path/to/shopgraph/dist/index.js"]
    }
  }
}