Global Shopaholics MCP server
by xuniwattoo
README.md
# Global Shopaholics MCP server
A public, remote [Model Context Protocol](https://modelcontextprotocol.io) server that lets any AI agent (Claude, ChatGPT, Cursor, Grok, …) help a person anywhere **buy from any US store and ship it through Global Shopaholics (GS)**.
It only wraps what GS already has: the website's live rate engine, published fees/plans, the sign-up flow, the Assisted Purchase request process and carrier tracking. Duty/VAT figures come from a small sourced rules table and are always labelled estimates.
- Transport: **Streamable HTTP** (stateless, JSON responses) at `/mcp`, plus a **stdio** entry.
- Runtime: web-standard `Request`/`Response` → runs on **Cloudflare Workers (primary)**, Vercel, or any Node ≥ 20 host (Cloudways).
- No auth for read tools. Lead tools are rate-limited per IP (hourly), per email (daily) and by a global daily cap; rate-lookup tools have a per-IP hourly cap. On Cloudflare Workers these limits live in a SQLite Durable Object; Node/Vercel fall back to a per-process in-memory limiter.
## Tools
| Tool | What it does |
|---|---|
| `get_shipping_rates` | Live DHL / FedEx / UPS / USPS prices, transit times, max weight/size, insurance text and dimensional-weight flag from GS's rate engine (`/wp-json/rate-calculator/v2/getrates`), normalized and sorted. |
| `estimate_landed_cost` | Item + optional US sales tax + GS Assisted Purchase fee (0% when paid by bank transfer or crypto, otherwise 5% (a minimum currently applies per the published site); expedited & executive per GS FAQ) + live shipping + estimated duty/VAT (AO, SA, AE, GB, CA, AU, NG, PK, IN, BR, DE, FR, NL). Optional Easyship Tax & Duty API when `EASYSHIP_API_KEY` and an HS code are given. |
| `get_services_and_fees` | Services, plans (Basic free, Premium $9.99, Business $14.99) and published fees with source URLs + last-checked date. |
| `get_started` | How to get the free US address (sign-up: `https://login.globalshopaholics.com/register`) and next steps. |
| `request_assisted_purchase` | Sends a "buy it for me" request to GS (GoHighLevel and/or webhook), tag `mcp-assisted-purchase`; returns a reference id. Falls back to GS's [Assisted Purchase page](https://globalshopaholics.com/assisted-purchase/) + prefilled email if no sink is configured. |
| `request_shipment_quote` | Same lead flow for manual quotes, labels, customs paperwork, freight; tag `mcp-shipping-request`. |
| `track_shipment` | Carrier tracking URL (DHL/FedEx/UPS/USPS, auto-detected). GS has no public tracking page; customers also see status in their dashboard. |
Resource: `gs://about` (markdown overview). Prompt: `buy-and-ship`.
## Run locally
```bash
npm install
cp .env.example .env # optional, every value has a default
npm run dev # Node server on http://localhost:8787/mcp
npm test # unit + in-process MCP tests (all network mocked)
npm run smoke # spawns the server, real HTTP MCP client, LIVE GS rates, lead sinks mocked
npm run cf:dev # same code inside the Cloudflare Workers runtime (wrangler dev)
npm run stdio # stdio transport
```
`npm run build && npm start` runs the compiled Node server (`dist/entry/node.js`).
## Connect an AI agent
The public MCP URL is `https://mcp.globalshopaholics.com/mcp`. Fallback: `https://gs-mcp.gshopaholics.workers.dev/mcp`.
**Claude (claude.ai / Claude Desktop)** – Settings → Connectors → *Add custom connector* → paste `https://mcp.globalshopaholics.com/mcp`. For older Claude Desktop builds without remote connectors, add to `claude_desktop_config.json`:
```json
{ "mcpServers": { "global-shopaholics": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.globalshopaholics.com/mcp"] } } }
```
**ChatGPT** – Settings → Apps & Connectors → Advanced → enable Developer mode → *Create* connector → MCP server URL `https://mcp.globalshopaholics.com/mcp`, authentication *No authentication*.
**Cursor** – `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
```json
{ "mcpServers": { "global-shopaholics": { "url": "https://mcp.globalshopaholics.com/mcp" } } }
```
**curl**
```bash
curl -s -X POST https://mcp.globalshopaholics.com/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_shipping_rates","arguments":{"country":"AO","weight":5,"unit":"kg"}}}'
```
## Configuration
See `.env.example` (Node/Vercel) or `wrangler.toml` `[vars]` + `wrangler secret put` (Workers). Full list in [docs/deploy.md](docs/deploy.md).
## Layout
```
src/config.ts env → typed config (works with Workers env or process.env)
src/server.ts McpServer: 7 tools, resource, prompt (zod schemas)
src/http.ts stateless web-standard Streamable HTTP handler, CORS, /health
src/entry/worker.ts Cloudflare Workers entry
src/entry/node.ts plain Node HTTP entry (Cloudways/VPS)
src/entry/stdio.ts stdio entry
api/mcp.ts, vercel.json Vercel entry
src/lib/rates.ts GS rate engine client + normalizer + 10-min cache
src/lib/landed.ts landed-cost estimator, GS fee logic, optional Easyship
src/lib/leads.ts GoHighLevel v2 / webhook lead sinks + fallback
src/lib/ratelimit.ts limiter contract + in-memory fallback
src/lib/limiter-do.ts SQLite Durable Object limiter (Workers)
src/lib/validate.ts lead-input sanitization and checks
src/lib/tracking.ts carrier detection + URLs
src/data/*.ts GS facts (sourced), duty rules (sourced), GS calculator country list
test/ vitest tests + fixture (real GS response, Angola 5 kg)
scripts/smoke.ts end-to-end smoke test
docs/ website page copy, deploy guide
server.json MCP registry manifest
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues