mcp-merchant

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)

• • Seed Stripe test data (uses your STRIPE_SECRET_KEY):

  make seed

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

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

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