{
  "markdown": "# MCP Merchant (ai.shawndurrani/mcp-merchant)\n\nStatus (plain English)\n- Listed in the public MCP Registry (discoverable metadata).\n- Runs locally via stdio from an NPM package; uses Stripe test mode and an in‑memory cache.\n- Verified end‑to‑end: seed → health (itemsCached) → searchProducts (returns results).\n- Hosted SSE is live at https://mcp.shawndurrani.ai/sse (health at /healthz).\n- Claude Desktop doesn’t auto‑discover from the registry yet; manual config or SSE URL works today.\n- Demo catalog: ~90–100 products in AUD, including sizes (seed v2).\n\nCurrent Release Summary (Sep 2025)\n- Registry lists SSE remote at version 0.1.3 (discoverable by clients).\n- AUD demo catalog seeding (v2) with sizes; old USD demo items are deactivated on seed.\n- 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.\n- Public hardening: security headers (Helmet) and gentle rate limiting on `/sse` and `/message`.\n\nHosted Endpoint (quick verify)\n- Health: open https://mcp.shawndurrani.ai/healthz — expect `{ \"status\": \"ok\", ... }`.\n- Inspector (SSE):\n\n  npx -y @modelcontextprotocol/inspector@latest --sse https://mcp.shawndurrani.ai/sse\n\n- In the UI: call `health`, then `searchProducts` (e.g., query \"mug\").\n- Note: Inspector may warn about Node version; it can still run. Upgrade Node later if desired.\n- 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.\n\nHealth endpoint details\n- `/healthz` now returns: `status`, `source`, `version`, `itemsCached`, `refreshedAgoSec`, and a masked Stripe account id `account` (e.g., `acct_1ABC…9Q2K`).\n- Use this to verify cache warm‑up and that the server is reading from the expected Stripe test account.\n\nChatGPT (Web) Setup\n- Enable Developer Mode (web app): Settings → Developer → toggle ON.\n- Add server: Settings → Model Context Protocol → Add Server → Type: `sse`, URL: `https://mcp.shawndurrani.ai/sse`.\n- Start a new chat → ensure your server is enabled under “Use tools” → run `ai.shawndurrani/mcp-merchant.health`, then `...searchProducts`.\n- Tip: If ChatGPT routes to GitHub instead, disable other connectors for that chat and retry.\n\nChatGPT (SSE) Quickstart\n- In ChatGPT MCP settings, add a server:\n  - Name: ai.shawndurrani/mcp-merchant\n  - Type: sse\n  - URL: https://mcp.shawndurrani.ai/sse\n- Then run `ai.shawndurrani/mcp-merchant.health` and `...searchProducts`.\n\nQuickstart (minimum to query products)\n- 1) Seed Stripe test data (uses your STRIPE_SECRET_KEY):\n\n  make seed\n\n- 2) Inspect and run tools locally (stdio via npx):\n\n  make inspector\n\n- In the Inspector UI, call `health`, then `searchProducts` (e.g., query \"mug\", page 1, pageSize 5).\n- Alternatively, run directly:\n\n  STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX \\\n  PRODUCT_LIMIT=100 \\\n  REFRESH_INTERVAL_SEC=600 \\\n  npx @modelcontextprotocol/inspector --stdio --command npx -- --yes mcp-merchant\n\nSeed the AUD catalog (~94 items)\n- Requires `STRIPE_SECRET_KEY` in env; deactivates old USD demo items automatically.\n\n  make seed\n\nSecurity Posture\n- No secrets in Git or the NPM package (see `docs/SECURITY.md`)\n- Private DNS key and `.env` are untracked and ignored\n- Public artifacts: DNS TXT (public key), registry entry, NPM package\n\nWhat this is\n- A tiny, registry‑listed MCP server that exposes search over a demo catalog.\n- MVP uses Stripe Products/Prices (test mode) as the catalog; Magento deferred.\n- Transports: NPM + stdio (local dev) and hosted SSE at `https://mcp.shawndurrani.ai/sse`.\n\nKey files\n- `server.json`: registry manifest (identifier/version must match NPM)\n- `.env.example`: environment variables (copy to `.env` locally)\n- `docs/PUBLISHING.md`: step‑by‑step publishing workflow\n\nDecisions\n- Name/namespace: `ai.shawndurrani/mcp-merchant`\n- Transport: start with NPM + stdio; add `remotes` (SSE at `https://mcp.shawndurrani.ai/sse`) later\n- Data source: Stripe test mode catalog (cached in memory)\n- MVP tools: `searchProducts`, `health`\n\nRegistry listing\n- Live query: https://registry.modelcontextprotocol.io/v0/servers?search=mcp-merchant&version=latest\n- 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\"`.\n\nMilestone recap (public vs private)\n- Public: DNS TXT with public key, NPM package `mcp-merchant@0.1.3`, registry entry for `ai.shawndurrani/mcp-merchant` (status: active)\n- Private: Ed25519 private key (local PEM), `.env` with Stripe key, publisher token in home dir\n\nUsing the MCP Inspector (stdio)\n- Why this form: inspector’s CLI sometimes mis-parses short flags after `--`. Using env from the shell and `--yes` avoids the ambiguity.\n- Command (replace with your test key):\n\n  STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX \\\n  PRODUCT_LIMIT=50 \\\n  REFRESH_INTERVAL_SEC=600 \\\n  npx @modelcontextprotocol/inspector --stdio --command npx -- --yes mcp-merchant\n\n- 3) One‑command demo (no UI; runs health + searchProducts):\n\n  make demo\n\n  - Uses `scripts/run_tools.js` to spawn the stdio server via `npx`, waits for the cache to warm, then prints tool outputs.\n  - Customize query via env:\n\n    MCP_QUERY=\"tee\" MCP_PAGE=1 MCP_PAGE_SIZE=5 make demo\n\n- 4) Claude Desktop (manual setup, current behavior)\n  - Claude doesn’t query the MCP Registry yet; add the server manually.\n  - Config: `~/Library/Application Support/Claude/claude_desktop_config.json`\n  - Example (uses `npx --yes mcp-merchant` and your env): see section below.\n\n- Alternative with inspector’s `--env` flags (keep args long-form and after `--`):\n\n  npx @modelcontextprotocol/inspector \\\n    --stdio \\\n    --command npx \\\n    --env STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX \\\n    --env PRODUCT_LIMIT=50 \\\n    --env REFRESH_INTERVAL_SEC=600 \\\n    -- --yes mcp-merchant\n\nClaude Desktop (manual setup, current behavior)\n- Claude Desktop does not query the central MCP Registry yet, so it won’t auto-discover this server. Add it manually in the config.\n- File: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Example entry:\n\n  Reliable setup (no npx; avoids spawn/permissions issues):\n\n  {\n    \"mcpServers\": {\n      \"ai.shawndurrani/mcp-merchant\": {\n        \"command\": \"/usr/local/bin/node\",\n        \"args\": [\"/Users/you/path/to/mcp-merchant/bin/index.js\"],\n        \"env\": {\n          \"STRIPE_SECRET_KEY\": \"sk_test_XXXXXXXXXXXXXXXXXXXXXXXX\",\n          \"PRODUCT_LIMIT\": \"100\",\n          \"REFRESH_INTERVAL_SEC\": \"600\"\n        }\n      }\n    }\n  }\n\n- Why this works: It launches your local entrypoint directly with your Node runtime, bypassing `npx` and any NPM cache/permission hiccups.\n- Verify: Settings → Developer → Connected Tools should show this server as “Connected”. Restart Claude after edits.\n\nHosted SSE in Claude Desktop (simple)\n- Add to `claude_desktop_config.json`:\n\n  {\n    \"mcpServers\": {\n      \"ai.shawndurrani/mcp-merchant\": {\n        \"type\": \"sse\",\n        \"url\": \"https://mcp.shawndurrani.ai/sse\"\n      }\n    }\n  }\n\n- Restart Claude; check Connected Tools. Run `...health` then `...searchProducts`.\n\nWhy manual configuration (even though it’s in the registry)\n- The MCP Registry is a public directory for discovery and metadata, but not all clients consume it yet.\n- Claude Desktop (current version) supports manual stdio/SSE configuration only; it does not automatically fetch from the registry.\n- Once clients add registry integration, manual steps should no longer be required.\n\nNotes on hosting\n- Hosted SSE is live at `https://mcp.shawndurrani.ai/sse`. Local stdio remains for development.\n- Next.js demo UI on Railway is optional and separate from MCP.\n\nCatalog (AUD)\n- The seeding script now creates ~94 items in AUD with categories and sizes (tagged `mcp_merchant_seed=v2`).\n- Older USD demo items (v1) are deactivated on seed.\n- If you raise the catalog size, increase `PRODUCT_LIMIT` accordingly.\n\nNotes\n- Keep tool schemas stable; add fields/tools rather than changing existing ones.\n- Secrets stay in `.env`; `.env.example` documents required keys.\n\nSearch behavior and tips\n- What’s indexed today: case‑insensitive substring match on `name` and `description` only.\n- 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.\n- Empty browse: use `listProducts` without a query and paginate via `page`/`pageSize` with `hasMore`.\n- 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.\n\nArchitecture & Rationale\n- See `docs/ARCHITECTURE.md` for a friendly overview of components, data flow, and why stdio + cache is the MVP.\n- See `docs/USAGE.md` for step‑by‑step usage, Inspector, demo, and Claude notes.\n\nFuture hosting and what simplifies\n- If you host the SSE server, clients can point to `https://mcp.shawndurrani.ai/sse` (no local Node or env vars).\n- You can then rely on the `remotes` entry in `server.json` to advertise the URL via the registry.\n- Local helpers (`scripts/run_tools.js`, `make demo`, manual Claude stdio config) become optional—useful for dev, not required for users.\n\nDocs map\n- Usage guide: `docs/USAGE.md` (Claude + ChatGPT MCP + Inspector, Tool reference)\n- Architecture: `docs/ARCHITECTURE.md`\n- Deployment: `docs/DEPLOYMENT.md` (Railway + Cloudflare DNS-only)\n- Publishing workflow: `docs/PUBLISHING.md`\n- Security notes: `docs/SECURITY.md`\n\nHow this works (plain English)\n- The MCP client (Inspector, Claude, or `scripts/run_tools.js`) launches the server via stdio (it runs as a child process).\n- On startup, the server refreshes an in-memory product catalog from Stripe test mode (limited by `PRODUCT_LIMIT`).\n- Tools you can call:\n  - `health`: reports status, data source, version, and how many items are cached.\n  - `searchProducts`: substring search over `name`/`description` with pagination and a `pageSize` safety cap.\n- 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.\n\nCLI cheat sheet\n- Install deps: `make setup`\n- Seed products: `make seed`\n- Inspector UI: `make inspector`\n- Run server only: `make run`\n- Demo (health + search): `make demo`",
  "bytes": 10732,
  "sha": "3d4e822bc508db5c3505e48db51815b350c8045a90a4cb5560a6244d761f6bc4",
  "repo_slug": "",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_shawndurrani_mcp_merchant_123fe2a7/readme"
}