ai.shawndurrani/mcp-merchant

Search-only commerce MCP server backed by Stripe (test)

Open source Open in the app JSON README (API)

About

Search-only commerce MCP server backed by Stripe (test)

Details

Kind

MCP servers

Topic

Finance & crypto

Publisher

ai.shawndurrani

Origin

official

Category

ferramentas

Transport

sse

Version

0.1.3

Added

2026-08-29 03:00:38

Updated

2026-08-29 03:00:38

Origin id

ai.shawndurrani/mcp-merchant

README

# MCP Merchant (ai.shawndurrani/mcp-merchant)

Status (plain English)
- Listed in the public MCP Registry (discoverable metadata).
- Runs locally via stdio from an NPM package; uses Stripe test mode and an in‑memory cache.
- Verified end‑to‑end: seed → health (itemsCached) → searchProducts (returns results).
- Hosted SSE is live at https://mcp.shawndurrani.ai/sse (health at /healthz).
- Claude Desktop doesn’t auto‑discover from the registry yet; manual config or SSE URL works today.
- Demo catalog: ~90–100 products in AUD, including sizes (seed v2).

Current Release Summary (Sep 2025)
- Registry lists SSE remote at version 0.1.3 (discoverable by clients).
- AUD demo catalog seeding (v2) with sizes; old USD demo items are deactivated on seed.
- Public Explorer lives at https://mcp-registry.shawndurrani.ai/explore (moved to the Registry service for same-origin data). The Explorer is snapshot-first (latest-only), SSE-only by default, supports infinite scroll, and instant sorting.
- Public hardening: security headers (Helmet) and gentle rate limiting on `/sse` and `/message`.

Hosted Endpoint (quick verify)
- Health: open https://mcp.shawndurrani.ai/healthz — expect `{ "status": "ok", ... }`.
- Inspector (SSE):

  npx -y @modelcontextprotocol/inspector@latest --sse https://mcp.shawndurrani.ai/sse

- In the UI: call `health`, then `searchProducts` (e.g., query "mug").
- Note: Inspector may warn about Node version; it can still run. Upgrade Node later if desired.
- Registry Explorer: https://mcp-registry.shawndurrani.ai/explore lets you browse servers and copy SSE URLs (SSE-only by default; toggle to include non-SSE). It shows total registry count, supports infinite scroll, and sorts by Name/Version.

Health endpoint details
- `/healthz` now returns: `status`, `source`, `version`, `itemsCached`, `refreshedAgoSec`, and a masked Stripe account id `account` (e.g., `acct_1ABC…9Q2K`).
- Use this to verify cache warm‑up and that the server is reading from the expected Stripe test account.

ChatGPT (Web) Setup
- Enable Developer Mode (web app): Settings → Developer → toggle ON.
- Add server: Settings → Model Context Protocol → Add Server → Type: `sse`, URL: `https://mcp.shawndurrani.ai/sse`.
- Start a new chat → ensure your server is enabled under “Use tools” → run `ai.shawndurrani/mcp-merchant.health`, then `...searchProducts`.
- Tip: If ChatGPT routes to GitHub instead, disable other connectors for that chat and retry.

ChatGPT (SSE) Quickstart
- In ChatGPT MCP settings, add a server:
  - Name: ai.shawndurrani/mcp-merchant
  - Type: sse
  - URL: https://mcp.shawndurrani.ai/sse
- Then run `ai.shawndurrani/mcp-merchant.health` and `...searchProducts`.

Quickstart (minimum to query products)
- 1) Seed Stripe test data (uses your STRIPE_SECRET_KEY):

  make seed

- 2) Inspect and run tools locally (stdio via npx):

  make inspector

- In the Inspector UI, call `health`, then `searchProducts` (e.g., query "mug", page 1, pageSize 5).
- Alternatively, run directly:

  STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX \
  PRODUCT_LIMIT=100 \
  REFRESH_INTERVAL_SEC=600 \
  npx @modelcontextprotocol/inspector --stdio --command npx -- --yes mcp-merchant

Seed the AUD catalog (~94 items)
- Requires `STRIPE_SECRET_KEY` in env; deactivates old USD demo items automatically.

  make seed

Security Posture
- No secrets in Git or the NPM package (see `docs/SECURITY.md`)
- Private DNS key and `.env` are untracked and ignored
- Public artifacts: DNS TXT (public key), registry entry, NPM package

What this is
- A tiny, registry‑listed MCP server that exposes search over a demo catalog.
- MVP uses Stripe Products/Prices (test mode) as the catalog; Magento deferred.
- Transports: NPM + stdio (local dev) and hosted SSE at `https://mcp.shawndurrani.ai/sse`.

Key files
- `server.json`: registry manifest (identifier/version must match NPM)
- `.env.example`: environment variables (copy to `.env` locally)
- `docs/PUBLISHING.md`: step‑by‑step publishing workflow

Decisions
- Name/namespace: `ai.shawndurrani/mcp-merchant`
- Transport: start with NPM + stdio; add `remotes` (SSE at `https://mcp.shawndurrani.ai/sse`) later
- Data source: Stripe test mode catalog (cached in memory)
- MVP tools: `searchProducts`, `health`

Registry listing
- Live query: https://registry.modelcontextprotocol.io/v0/servers?search=mcp-merchant&version=latest
- Shows `ai.shawndurrani/mcp-merchant@0.1.3` with NPM stdio transport and documented env vars, plus the hosted SSE remote. Entry includes `status: "active"`.

Milestone recap (public vs private)
- Public: DNS TXT with public key, NPM package `mcp-merchant@0.1.3`, registry entry for `ai.shawndurrani/mcp-merchant` (status: active)
- Private: Ed25519 private key (local PEM), `.env` with Stripe key, publisher token in home dir

Using the MCP Inspector (stdio)
- Why this form: inspector’s CLI sometimes mis-parses short flags after `--`. Using env from the shell and `--yes` avoids the ambiguity.
- Command (replace with your test key):

  STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX \
  PRODUCT_LIMIT=50 \
  REFRESH_INTERVAL_SEC=600 \
  npx @modelcontextprotocol/inspector --stdio --command npx -- --yes mcp-merchant

- 3) One‑command demo (no UI; runs health + searchProducts):

  make demo

  - Uses `scripts/run_tools.js` to spawn the stdio server via `npx`, waits for the cache to warm, then prints tool outputs.
  - Customize query via env:

    MCP_QUERY="tee" MCP_PAGE=1 MCP_PAGE_SIZE=5 make demo

- 4) Claude Desktop (manual setup, current behavior)
  - Claude doesn’t query the MCP Registry yet; add the server manually.
  - Config: `~/Library/Application Support/Claude/claude_desktop_config.json`
  - Example (uses `npx --yes mcp-merchant` and your env): see section below.

- Alternative with inspector’s `--env` flags (keep args long-form and after `--`):

  npx @modelcontextprotocol/inspector \
    --stdio \
    --command npx \
    --env STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX \
    --env PRODUCT_LIMIT=50 \
    --env REFRESH_INTERVAL_SEC=600 \
    -- --yes mcp-merchant

Claude Desktop (manual setup, current behavior)
- Claude Desktop does not query the central MCP Registry yet, so it won’t auto-discover this server. Add it manually in the config.
- File: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Example entry:

  Reliable setup (no npx; avoids spawn/permissions issues):

  {
    "mcpServers": {
      "ai.shawndurrani/mcp-merchant": {
        "command": "/usr/local/bin/node",
        "args": ["/Users/you/path/to/mcp-merchant/bin/index.js"],
        "env": {
          "STRIPE_SECRET_KEY": "sk_test_XXXXXXXXXXXXXXXXXXXXXXXX",
          "PRODUCT_LIMIT": "100",
          "REFRESH_INTERVAL_SEC": "600"
        }
      }
    }
  }

- Why this works: It launches your local entrypoint directly with your Node runtime, bypassing `npx` and any NPM cache/permission hiccups.
- Verify: Settings → Developer → Connected Tools should show this server as “Connected”. Restart Claude after edits.

Hosted SSE in Claude Desktop (simple)
- Add to `claude_desktop_config.json`:

  {
    "mcpServers": {
      "ai.shawndurrani/mcp-merchant": {
        "type": "sse",
        "url": "https://mcp.shawndurrani.ai/sse"
      }
    }
  }

- Restart Claude; check Connected Tools. Run `...health` then `...searchProducts`.

Why manual configuration (even though it’s in the registry)
- The MCP Registry is a public directory for discovery and metadata, but not all clients consume it yet.
- Claude Desktop (current version) supports manual stdio/SSE configuration only; it does not automatically fetch from the registry.
- Once clients add registry integration, manual steps should no longer be required.

Notes on hosting
- Hosted SSE is live at `https://mcp.shawndurrani.ai/sse`. Local stdio remains for development.
- Next.js demo UI on Railway is optional and separate from MCP.

Catalog (AUD)
- The seeding script now creates ~94 items in AUD with categories and sizes (tagged `mcp_merchant_seed=v2`).
- Older USD demo items (v1) are deactivated on seed.
- If you raise the catalog size, increase `PRODUCT_LIMIT` accordingly.

Notes
- Keep tool schemas stable; add fields/tools rather than changing existing ones.
- Secrets stay in `.env`; `.env.example` documents required keys.

Search behavior and tips
- What’s indexed today: case‑insensitive substring match on `name` and `description` only.
- Practical impact: queries like "tee", "hoodie", "mug" work well if those words appear in the product name/description. A query like "shirt" won’t match unless the word appears in the text.
- Empty browse: use `listProducts` without a query and paginate via `page`/`pageSize` with `hasMore`.
- Metadata recommendations: include helpful Stripe Product `metadata` such as `category` (e.g., Apparel), `subcategory` (e.g., T‑Shirts), `size` (e.g., S), and `tags` (e.g., ["shirt","tee","apparel"]). The current MVP does not filter on metadata yet, but future versions may add metadata‑aware filters.

Architecture & Rationale
- See `docs/ARCHITECTURE.md` for a friendly overview of components, data flow, and why stdio + cache is the MVP.
- See `docs/USAGE.md` for step‑by‑step usage, Inspector, demo, and Claude notes.

Future hosting and what simplifies
- If you host the SSE server, clients can point to `https://mcp.shawndurrani.ai/sse` (no local Node or env vars).
- You can then rely on the `remotes` entry in `server.json` to advertise the URL via the registry.
- Local helpers (`scripts/run_tools.js`, `make demo`, manual Claude stdio config) become optional—useful for dev, not required for users.

Docs map
- Usage guide: `docs/USAGE.md` (Claude + ChatGPT MCP + Inspector, Tool reference)
- Architecture: `docs/ARCHITECTURE.md`
- Deployment: `docs/DEPLOYMENT.md` (Railway + Cloudflare DNS-only)
- Publishing workflow: `docs/PUBLISHING.md`
- Security notes: `docs/SECURITY.md`

How this works (plain English)
- The MCP client (Inspector, Claude, or `scripts/run_tools.js`) launches the server via stdio (it runs as a child process).
- On startup, the server refreshes an in-memory product catalog from Stripe test mode (limited by `PRODUCT_LIMIT`).
- Tools you can call:
  - `health`: reports status, data source, version, and how many items are cached.
  - `searchProducts`: substring search over `name`/`description` with pagination and a `pageSize` safety cap.
- The MCP Registry entry makes your server publicly discoverable, but Claude Desktop doesn’t consume the registry yet, so we add it manually to Claude’s config.

CLI cheat sheet
- Install deps: `make setup`
- Seed products: `make seed`
- Inspector UI: `make inspector`
- Run server only: `make run`
- Demo (health + search): `make demo`

More

• More mcp servers on Finance & crypto
• Everything published by ai.shawndurrani
• Browse the whole catalog