Skip to main content
Glama
Global Shopaholics MCP server

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
```